How to create APEX 5 Plugins?

My first ORACLE APEX 5 Plugin notes

How hard it is to do this?

It has been a while since APEX plugins were introduced to APEX and I used them in my projects but I wanted to give it a try to see how easy it is to create one. Finally found some time to do write my notes about it.

There are 6 types of plugins in APEX 5.0 and each follows special implementation method

In this short demo I will create a simple Dynamic Action plugin that simply will execute a call of my JavaScript when page loads.

First step is to create a plugin so navigate in your Application Builder -> Shared Components -> plugins -> Create Plugin.

Give you plugin a name and select what type of plugin we are creating.

Then we need to create a PL SQL logic for this plugin.

 -- The render function generates the necessary javascript code for the
-- dynamic action plug-in and registers this function with the dynamic action
-- client side framework.
-- The render function has a defined interface which every plug-in has to
-- implement. It's designed in a way that future enhancements to the interface
-- will not break existing plug-ins.
function add_my_javascripts (
    p_dynamic_action in apex_plugin.t_dynamic_action,
    p_plugin         in apex_plugin.t_plugin )
    return apex_plugin.t_dynamic_action_render_result
is
    l_result apex_plugin.t_dynamic_action_render_result;
begin
    -- During plug-in development it's very helpful to have some debug information
    if apex_application.g_debug then
        apex_plugin_util.debug_dynamic_action (
            p_plugin         => p_plugin,
            p_dynamic_action => p_dynamic_action );
    end if;
    -- ***********************************
    -- Here starts the actual plug-in code
    -- ***********************************
    -- Register the javascript library the plug-in uses.
    -- The add_library call will make sure that just one instance of the
    -- library is loaded when the plug-in is used multiple times on the page.
    -- If the developer stores the javascript file on the web-server, the
    -- p_plugin.file_prefix will contain the web-server URL. If the variable
    -- contains #PLUGIN_PREFIX#, the file will be read from the database.
    apex_javascript.add_library (
        p_name      => 'Any_JavaScript',
        p_directory => p_plugin.file_prefix,
        p_version   => null );
       
    l_result.javascript_function := 'demo';
    return l_result;
end add_my_javascripts;

There are two key points in this code and these are function name plus a JS library call.

Why? Name of this function will be used by APEX to render your plugin. 

Notice that my function name is parameter for Render Function Name parameter. Also input and return parameters are standard parameters used in Dynamic Action plugin type. For other plugin type examples please reference to Orace APEX documentation or check some of your existing plugins for details. 

Secondly is add_library function that adds your JavaScript so that it can be used within this plugin.

Two things to note, 'the best practice' way of doing this PL/SQL function is to put it in a package in your DB for ease of debugging plus it will make your code to render more quickly. 

Also before just jumping to it consider naming your plugins, functions and files uses following some standard naming conventions like -> com_yourcompany_apex_get_data 

Once you are done with this code select Create Plugin. Now we have to add file that we are using in code above. Under files you upload your JS scripts.

For this demo my JS contains only one dummy function. 

function demo(){
alert('Hi there!');
}

If you save your changes and create anywhere in your application a DA with Onload Action -> 'name of this plugin' you should get this message in your APEX page. 

 

To summarize plugins are a great way for developers to share their work, they can be reused multiple times in different places or applications with a simple export import capabilities and above all gives you the ability to implement any sort of "new feature" to extend original APEX capabilities.

Especially can be useful if you do not have access to your servers and need to quickly test your JS code or include some new libraries.

Soon I will do another demo when I will create a "Retrieve Twitter tweeds" plugin with parameters and some more logic.

General hint how to start with APEX plugin? 

Firstly get and use plugins from APEX-PLUGIN.com also there are so many useful but hidden plugins in Packaged apps. Once you install these have a quick look to see what is going on in the background as this will make it clear and give you all you need to start experimenting with your own ideas.

Cheers,

SLino