Getting Started with APEX Plugins

There is a great deal you can build in APEX without even thinking about using a plugin. The development platform has an excellent range of built-in functionality and components so that almost all user requirements can be covered using standard APEX features. Restricting yourself to only the built-in, declarative features (i.e. “low code”) of the tool will result in applications that are easy to maintain and resistant to regression issues when upgrading. However, there will come a time when some custom code is required, whether some special data processing (using PL/SQL), some special user interface styling (using CSS), or some special user interface behaviour (using JavaScript or jQuery).

After you have built an application with (a minimum of) custom code like this, it sometimes happens that the same user requirement crops up again elsewhere; whether on another page, another application, or another workspace. The first time you encounter this you will probably just do a “copy and paste” to replicate the custom code. When you encounter the requirement a third time, you should be asking yourself, “how can I make this code more re-usable” – because chances are one day you’ll need to fix a bug or make an enhancement to that code, and you’ll want it to be easy to deploy the change wherever it has been used. This is where an APEX plugin could be a suitable solution.

This post is mostly based on a talk given in October 2019 at the Australian Oracle User Group conference in Perth, Western Australia.

What is an APEX Plugin?

An APEX Plugin is a Shared Component that can be used in any number of pages in the application. When used, it generates a Region, an Item, a Process, or a Dynamic Action; or, it may implement an Authentication or Authorization Scheme. It is a self-contained set of attributes, code, and (optionally) file attachments. It may be copied to another application, or exported as a SQL script for importing into an application in another workspace or another APEX instance.

Where can I get started?

In my opinion, a great way to get started learning about plugins is to examine a lot of plugins that others have created. The two sources I would recommend you look at are:

  1. Install the Sample Database Application – go into its Shared Components -> Plugins, and look at each of the plugins therein. Look through each attribute and examine the code; read the help for each attribute as well. Look at how the plugins are used in the application.
  2. Browse the plugins at apex.world, and install a few that seem interesting to you.

When looking at these plugins, be aware that many of them have been created by people just like you and me – at differing levels of experience and skill; so they may or may not perfectly reflect “best practice”. This especially goes for the plugins published by yours truly :). In addition, depending on how long ago a plugin was written, it might be more complex than it needs to be, as it might not take advantage of recent enhancements to the APEX plugin API.

Plugin Concepts

Plugin Types

Plugin Type – a plugin may be for a page Region, a page Item, a page Process or a Dynamic Action; or it may implement an Authentication Scheme or an Authorization Scheme. For example, if you create or install an Item Plugin, it will appear in the list of item types available for adding to a page.

PL/SQL and Callbacks – if needed, you can embed PL/SQL code that APEX will call when rendering the plugin component or for other events such as handling an AJAX callback or validating an item.

The Callbacks attributes allow you to specify the name of the function for APEX to call; these might be functions that you define within the PL/SQL Code section, or they can call functions in a database package you have defined.

The functions you define must have the exact parameters and return types as documented in the help for each Callback attribute.

Standard & Custom Attributes – some plugin types have Standard Attributes (defined by APEX), and can have additional Custom Attributes (defined by you). For example, a Region plugin has standard attributes that define whether it supports a Data Source or supports the CSS Classes attribute.

If needed you can define up to 15 custom Application attributes. These would be set by the developer when they first install the plugin into their application, and their values apply to all usages of the plugin across their application.

You can also define up to 25 custom Component attributes, which are set on each usage of the plugin separately. The developer will find these in the Attributes node.

Each Custom attribute can be any of a long list of different types, including Text, TextArea, Yes/No, Number, Checkboxes, Select list, Item name, Icon, PL/SQL Code, JavaScript Code, and many others. You can provide a default value for each attribute if needed.

Files, JS and CSS – you can attach any number of resources including JavaScript, CSS scripts, images, or anything else that are required by your plugin. To load JavaScript or CSS files on pages where your plugin is used, you can simply enter them in the File URLs to Load, or call the APEX API routines in your render PL/SQL code (e.g. APEX_JAVASCRIPT.add_library or APEX_CSS.add_file).

When you export the plugin, all the attached resources will be included in the SQL script.

Plugin Events – if your plugin needs to allow your developers to add Dynamic Actions that respond to events raised by your plugin (e.g. to respond to user actions) you can define any number of custom Events here.

Walkthroughs

I’ve written these instructions to get you started creating plugins. They assume you are already reasonably familiar with building simple applications in APEX, and are comfortable editing PL/SQL.

Resources

User-editable Application Setting
Loading large GeoJSON objects

Comments

  1. That’s a very good introduction for new developers, good job! Your walkthroughs are great especially showing that you can lower the overheads/barrier using a template based approach (thanks Daniel) and how quick you can create one without much effort.

    If you’re reading this as a developer new to APEX or haven’t yet created your first plugin then I would also really encourage you to give it a go.

    I’m not sure if it’s because where I am in my career i.e. 18 years in, and a lot of lessons learned on the way… but my love of the plugin interface is that it’s enforces structure on your development which is what we need when we are getting started as developers.

    Plugins have many benefits like: write once approach, atomic, loosely coupled, easy to use, easier to document thanks to integrated help in the builder, easy(ier) to version control, easier to centralize using subscriptions, easy to share, the list goes on. These are all fall into best development practices and things we should strive to do as professional developers.

    Another big plus for building them is that it will help you get into the frame of design of how to make your code more reusable and flexible, since you define plugin settings that the developer (end user of your plugin) can tweak to tailor to their particular requirement. This style of thinking tends to improve your problem solving ability over time because you look at a bigger picture.

    I think I would label plugins for those APEX Developers that want to be software engineers, not just regular developers: https://hackernoon.com/whats-the-difference-between-a-developer-and-an-engineer-1e7a97fc1bd

    What role do you want be?

    Just like every good sporting team there are different roles to play, being a plugin developer on your team will make your team better.

    There is one caveat, the more plugins you create the more you need to focus on your dev ops and making the management/deployment easier. So keep this in mind. That said you most probably are already doing this for your apps, and if you’re not then it’s another great learning path to becoming a better full stack APEX developer.

    So be sure to follow Jeff’s walkthrough’s and create your own, but be aware that once you start you might not be able to stop 😉

  2. Hello, in the interactive grid regions you have the option of actions where I can add a column. How do I also export this result to .csv? I used APEX_IR.GET_LAST_VIEWED_REPORT_ID and it didn’t work

    • Hi Daiane,

      That doesn’t seem to relate to the subject of this post, but anyway: if you are dynamically adding a column to an Interactive Grid, client-side, that column will not be available on the server, which is where the CSV file is generated. You will need to include the column in the data source for the grid.

      I hope that answers your question.

      Jeff

  3. hi jeff ,
    I am trying to import/export plugin from one workspace to another workspace. I have tried but I am getting an error ORA-00001: unique constraint (APEX_190200.WWV_FLOW_PLUGIN_PK) violated.

    how can I solve this error?

    • Hi Dixit,

      You can’t import a plugin into a workspace – you can import a plugin into an application in the other workspace, or you can import the application that contains the plugin into the other workspace.

      Jeff

Leave a Reply

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