Getting Started with APEX Plugins
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:
- 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.
- 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 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.
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.
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.
- Oracle documentation:
- APEX PL/SQL API:
- Plugin Templates – repository maintained by Daniel Hochleitner: github.com/Dani3lSun/apex-plugin-templates
- Published plugins:
1 November 2019 - 5:26 pm
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 😉
5 August 2020 - 6:56 pm
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
5 August 2020 - 8:20 pm
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.
24 September 2020 - 2:30 pm
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?
24 September 2020 - 2:42 pm
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.