APEX Plug-ins

Exclusive offer: get 50% off this eBook here
Oracle APEX Cookbook : Second Edition

Oracle APEX Cookbook : Second Edition — Save 50%

Create reliable, modern web applications for desktop and mobile devices with Oracle Application Express with this book and ebook

$35.99    $18.00
by Marcel Van Der Plas Michael Van Horenbeeck | October 2013 | Cookbooks Enterprise Articles Oracle

In this article created by Marcel van der Plas and Michel van Zoestauthor of Oracle APEX Cookbook, we will cover the following topics:

  • Creating an item type plug-in
  • Creating a region type plug-in
  • Creating a dynamic action plug-in
  • Creating a process type plug-in
  • Creating an authorization plug-in

(For more resources related to this topic, see here.)

In APEX 4.0, Oracle introduced the plug-in feature. A plug-in is an extension to the existing functionality of APEX. The idea behind plug-ins is to make life easier for developers. Plug-ins are reusable, and can be exported and imported. In this way it is possible to create a functionality which is available to all APEX developers. And installing and using them without the need of having a knowledge of what's inside the plug-in.

APEX translates settings from the APEX builder to HTML and JavaScript. For example, if you created a text item in the APEX builder, APEX converts this to the following code (simplified):

<input type="text" id="P12_NAME" name="P12_NAME" value="your name">

When you create an item type plug-in, you actually take over this conversion task of APEX, and you generate the HTML and JavaScript code yourself by using PL/SQL procedures. That offers a lot of flexibility because now you can make this code generic, so that it can be used for more items.

The same goes for region type plug-ins. A region is a container for forms, reports, and so on. The region can be a div or an HTML table. By creating a region type plug-in, you create a region yourself with the possibility to add more functionality to the region.

Plug-ins are very useful because they are reusable in every application. To make a plug-in available, go to Shared Components | Plug-ins , and click on the Export Plug-in link on the right-hand side of the page. Select the desired plug-in and file format and click on the Export Plug-in button. The plug-in can then be imported into another application.

Following are the six types of plug-in:

  • Item type plug-ins
  • Region type plug-ins
  • Dynamic action plug-ins
  • Process type plug-ins
  • Authorization scheme type plug-ins
  • Authentication scheme type plug-ins

In this Aricle we will discuss the first five types of plug-ins.

Creating an item type plug-in

In an item type plug-in you create an item with the possibility to extend its functionality. To demonstrate this, we will make a text field with a tooltip. This functionality is already available in APEX 4.0 by adding the following code to the HTML form element attributes text field in the Element section of the text field:

onmouseover="toolTip_enable(event,this,'A tooltip')"

But you have to do this for every item that should contain a tooltip. This can be made more easily by creating an item type plug-in with a built-in tooltip. And if you create an item of type plug-in, you will be asked to enter some text for the tooltip.

Getting ready

For this recipe you can use an existing page, with a region in which you can put some text items.

How to do it...

Follow these steps:

  1. Go to Shared Components | User Interface | Plug-ins .

  2. Click on the Create button.
  3. In the Name section, enter a name in the Name text field. In this case we enter tooltip.
  4. In the Internal Name text field, enter an internal name. It is advised to use the company's domain address reversed to ensure the name is unique when you decide to share this plug-in. So for example you can use com.packtpub.apex.tooltip.
  5. In the Source section, enter the following code in the PL/SQL Code text area:

    function render_simple_tooltip ( p_item in apex_plugin.t_page_item , p_plugin in apex_plugin.t_plugin , p_value in varchar2 , p_is_readonly in boolean , p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result is l_result apex_plugin.t_page_item_render_result; begin if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin , p_page_item => p_item , p_value => p_value , p_is_readonly => p_is_readonly , p_is_printer_friendly => p_is_printer_friendly); end if; -- sys.htp.p('<input type="text" id="'||p_item.name||'" name="'||p_
    item.name||'" class="text_field" onmouseover="toolTip_
    enable(event,this,'||''''||p_item.attribute_01||''''||')">');
    --
    return l_result;
    end render_simple_tooltip;

    This function uses the sys.htp.p function to put a text item (<input type="text") on the screen. On the text item, the onmouseover event calls the function toolTip_enable(). This function is an APEX function, and can be used to put a tooltip on an item. The arguments of the function are mandatory.

    The function starts with the option to show debug information. This can be very useful when you create a plug-in and it doesn't work. After the debug information, the htp.p function puts the text item on the screen, including the call to tooltip_enable. You can also see that the call to tooltip_enable uses p_item.attribute_01. This is a parameter that you can use to pass a value to the plug-in. That is, the following steps in this recipe.

    The function ends with the return of l_result. This variable is of the type apex_plugin.t_page_item_render_result. For the other types of plug-in there are dedicated return types also, for example t_region_render_result.

  6. Click on the Create Plug-in button
  7. The next step is to define the parameter (attribute) for this plug-in. In the Custom Attributes section, click on the Add Attribute button.

  8. In the Name section, enter a name in the Label text field, for example tooltip.
  9. Ensure that the Attribute text field contains the value 1 .
  10. In the Settings section, set the Type field to Text .
  11. Click on the Create button.
  12. In the Callbacks section, enter render_simple_tooltip into the Render Function Name text field.
  13. In the Standard Attributes section, check the Is Visible Widget checkbox.
  14. Click on the Apply Changes button.

    The plug-in is now ready. The next step is to create an item of type tooltip plug-in.

  15. Go to a page with a region where you want to use an item with a tooltip.
  16. In the Items section, click on the add icon to create a new item.

  17. Select Plug-ins .

  18. Now you will get a list of the available plug-ins. Select the one we just created, that is tooltip . Click on Next .
  19. In the Item Name text field, enter a name for the item, for example, tt_item.
  20. In the Region drop-down list, select the region you want to put the item in. Click on Next .
  21. In the next step you will get a new option. It's the attribute you created with the plug-in. Enter here the tooltip text, for example, This is tooltip text. Click on Next .
  22. In the last step, leave everything as it is and click on the Create Item button.
  23. You are now ready. Run the page. When you move your mouse pointer over the new item, you will see the tooltip.

How it works...

As stated before, this plug-in actually uses the function htp.p to put an item on the screen. Together with the call to the JavaScript function, toolTip_enable on the onmouseover event makes this a text item with a tooltip, replacing the normal text item.

There's more...

The tooltips shown in this recipe are rather simple. You could make them look better, for example, by using the Beautytips tooltips. Beautytips is an extension to jQuery and can show configurable help balloons. Visit http://plugins.jquery.com to download Beautytips. We downloaded Version 0.9.5-rc1 to use in this recipe.

  1. Go to Shared Components and click on the Plug-ins link.
  2. Click on the tooltip plug-in you just created.
  3. In the Source section, replace the code with the following code:

    function render_simple_tooltip ( p_item in apex_plugin.t_page_item, p_plugin in apex_plugin.t_plugin, p_value in varchar2, p_is_readonly in boolean, p_is_printer_friendly in boolean ) return apex_plugin.t_page_item_render_result is l_result apex_plugin.t_page_item_render_result; begin if apex_application.g_debug then apex_plugin_util.debug_page_item ( p_plugin => p_plugin , p_page_item => p_item , p_value => p_value , p_is_readonly => p_is_readonly , p_is_printer_friendly => p_is_printer_friendly); end if;

The function also starts with the debug option to see what happens when something goes wrong.

--Register the JavaScript and CSS library the plug-inuses. apex_javascript.add_library ( p_name => 'jquery.bgiframe.min', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'jquery.bt.min', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'jquery.easing.1.3', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'jquery.hoverintent.minified', p_directory => p_plugin.file_prefix, p_version => null ); apex_javascript.add_library ( p_name => 'excanvas', p_directory => p_plugin.file_prefix, p_version => null );

After that you see a number of calls to the function apex_javascript.add_library. These libraries are necessary to enable these nice tooltips. Using apex_javascript.add_library ensures that a JavaScript library is included in the final HTML of a page only once, regardless of how many plug-in items appear on that page.

sys.htp.p('<input type="text" id="'||p_item.name||'"
class="text_field" title="'||p_item.attribute_01||'">');
-- apex_javascript.add_onload_code (p_code =>'$("#'||p_item.name||'").bt({ padding: 20 , width: 100 , spikeLength: 40 , spikeGirth: 40 , cornerRadius: 50 , fill: '||''''||'rgba(200, 50, 50, .8)'||''''||' , strokeWidth: 4 , strokeStyle: '||''''||'#E30'||''''||' , cssStyles: {color: '||''''||'#FFF'||''''||',
fontWeight: '||''''||'bold'||''''||'} });'); -- return l_result; end render_tooltip;

Another difference with the first code is the call to the Beautytips library. In this call you can customize the text balloon with colors and other options. The onmouseover event is not necessary anymore as the call to $().bt in the wwv_flow_javascript.add_onload_code takes over this task. The $().bt function is a jQuery JavaScript function which references the generated HTML of the plug-in item by ID, and converts it dynamically to show a tooltip using the Beautytips plug-in.

You can of course always create extra plug-in item type parameters to support different colors and so on per item.

To add the other libraries, do the following:

  1. In the Files section, click on the Upload new file button.
  2. Enter the path and the name of the library. You can use the file button to locate the libraries on your filesystem. Once you have selected the file, click on the Upload button.

    The files and their locations can be found in the following table:

    Libra ry

    Location

    jquery.bgiframe.min.js

    \bt-0.9.5-rc1\other_libs\bgiframe_2.1.1

    jquery.bt.min.js

    \bt-0.9.5-rc1

    jquery.easing.1.3.js

    \bt-0.9.5-rc1\other_libs

    jquery.hoverintent.minified.js

    \bt-0.9.5-rc1\other_libs

    Excanvas.js

    \bt-0.9.5-rc1\other_libs\excanvas_r3

     

     

  3. If all libraries have been uploaded, the plug-in is ready. The tooltip now looks quite different, as shown in the following screenshot:

In the plug-in settings, you can enable some item-specific settings. For example, if you want to put a label in front of the text item, check the Is Visible Widget checkbox in the Standard Attributes section.

For more information on this tooltip, go to http://plugins.jquery.com/project/bt.

Creating a region type plug-in

As you may know, a region is actually a div. With the region type plug-in you can customize this div. And because it is a plug-in, you can reuse it in other pages. You also have the possibility to make the div look better by using JavaScript libraries. In this recipe we will make a carousel with switching panels. The panels can contain images but they can also contain data from a table. We will make use of another jQuery extension, Step Carousel.

Getting ready

You can download stepcarousel.js from http://www.dynamicdrive.com/dynamicindex4/stepcarousel.htm. However, in order to get this recipe work in APEX, we needed to make a slight modification in it. So, stepcarousel.js, arrowl.gif, and arrow.gif are included in this book.

How to do it...

Follow the given steps, to create the plug-in:

  1. Go to Shared Components and click on the Plug-ins link.
  2. Click on the Create button.
  3. In the Name section, enter a name for the plug-in in the Name field. We will use Carousel.
  4. In the Internal Name text field, enter a unique internal name. It is advised to use your domain reversed, for example com.packtpub.carousel.
  5. In the Type listbox, select Region .
  6. In the Source section, enter the following code in the PL/SQL Code text area:

    function render_stepcarousel ( p_region in apex_plugin.t_region, p_plugin in apex_plugin.t_plugin, p_is_printer_friendly in boolean ) return apex_plugin.t_region_render_result is cursor c_crl is select id , panel_title , panel_text , panel_text_date from app_carousel order by id; -- l_code varchar2(32767); begin

    The function starts with a number of arguments. These arguments are mandatory, but have a default value. In the declare section there is a cursor with a query on the table APP_CAROUSEL. This table contains several data to appear in the panels in the carousel.

    -- add the libraries and stylesheets -- apex_javascript.add_library ( p_name => 'stepcarousel', p_directory => p_plugin.file_prefix, p_version => null ); -- --Output the placeholder for the region which is used by--the Javascript code

    The actual code starts with the declaration of stepcarousel.js. There is a function, APEX_JAVASCRIPT.ADD_LIBRARY to load this library. This declaration is necessary, but this file needs also to be uploaded in the next step. You don't have to use the extension .js here in the code.

    -- sys.htp.p('<style type="text/css">'); -- sys.htp.p('.stepcarousel{'); sys.htp.p('position: relative;'); sys.htp.p('border: 10px solid black;'); sys.htp.p('overflow: scroll;'); sys.htp.p('width: '||p_region.attribute_01||'px;'); sys.htp.p('height: '||p_region.attribute_02||'px;'); sys.htp.p('}'); -- sys.htp.p('.stepcarousel .belt{'); sys.htp.p('position: absolute;'); sys.htp.p('left: 0;'); sys.htp.p('top: 0;'); sys.htp.p('}'); sys.htp.p('.stepcarousel .panel{'); sys.htp.p('float: left;'); sys.htp.p('overflow: hidden;'); sys.htp.p('margin: 10px;'); sys.htp.p('width: 250px;'); sys.htp.p('}'); -- sys.htp.p('</style>');

    After the loading of the JavaScript library, some style elements are put on the screen. The style elements could have been put in a Cascaded Style Sheet (CSS ), but since we want to be able to adjust the size of the carousel, we use two parameters to set the height and width. And the height and the width are part of the style elements.

    -- sys.htp.p('<div id="mygallery" class="stepcarousel"
    style="overflow:hidden"><div class="belt">'); -- for r_crl in c_crl loop sys.htp.p('<div class="panel">'); sys.htp.p('<b>'||to_char(r_crl.panel_text_date,'DD-MON-YYYY')||'</b>'); sys.htp.p('<br>'); sys.htp.p('<b>'||r_crl.panel_title||'</b>'); sys.htp.p('<hr>'); sys.htp.p(r_crl.panel_text); sys.htp.p('</div>'); end loop; -- sys.htp.p('</div></div>');

    The next command in the script is the actual creation of a div. Important here is the name of the div and the class. The Step Carousel searches for these identifiers and replaces the div with the stepcarousel. The next step in the function is the fetching of the rows from the query in the cursor. For every line found, the formatted text is placed between the div tags. This is done so that Step Carousel recognizes that the text should be placed on the panels.

    --Add the onload code to show the carousel -- l_code := 'stepcarousel.setup({ galleryid: "mygallery" ,beltclass: "belt" ,panelclass: "panel" ,autostep: {enable:true, moveby:1, pause:3000} ,panelbehavior: {speed:500, wraparound:true,persist:true} ,defaultbuttons: {enable: true, moveby: 1,
    leftnav:
    ["'||p_plugin.file_prefix||'arrowl.gif", -5,
    80], rightnav:
    ["'||p_plugin.file_prefix||'arrowr.gif", -20,
    80]} ,statusvars: ["statusA", "statusB", "statusC"] ,contenttype: ["inline"]})'; -- apex_javascript.add_onload_code (p_code => l_code); -- return null; end render_stepcarousel;

    The function ends with the call to apex_javascript.add_onload_code. Here starts the actual code for the stepcarousel and you can customize the carousel, like the size, rotation speed and so on.

  7. In the Callbacks section, enter the name of the function in the Return Function Name text field. In this case it is render_stepcarousel.
  8. Click on the Create Plug-in button.
  9. In the Files section, upload the stepcarousel.js, arrowl.gif, and arrowr.gif files.

    For this purpose, the file stepcarousel.js has a little modification in it. In the last section (setup:function), document.write is used to add some style to the div tag. Unfortunately, this will not work in APEX, as document.write somehow destroys the rest of the output. So, after the call, APEX has nothing left to show, resulting in an empty page. Document.write needs to be removed, and the following style elements need to be added in the code of the plug-in:

    sys.htp.p('</p><div id="mygallery" class="stepcarousel" style="overflow: hidden;"><div class="belt">');

    In this line of code you see style='overflow:hidden'. That is the line that actually had to be included in stepcarousel.js. This command hides the scrollbars.

  10. After you have uploaded the files, click on the Apply Changes button. The plug-in is ready and can now be used in a page.
  11. Go to the page where you want this stepcarousel to be shown.
  12. In the Regions section, click on the add icon.
  13. In the next step, select Plug-ins .
  14. Select Carousel .
  15. Click on Next .
  16. Enter a title for this region, for example Newscarousel. Click on Next .
  17. In the next step, enter the height and the width of the carousel. To show a carousel with three panels, enter 800 in the Width text field. Enter 100 in the Height text field. Click on Next .
  18. Click on the Create Region button.
  19. The plug-in is ready. Run the page to see the result.

How it works...

The stepcarousel is actually a div. The region type plug-in uses the function sys.htp.p to put this div on the screen. In this example, a div is used for the region, but a HTML table can be used also. An APEX region can contain any HTML output, but for the positioning, mostly a HTML table or a div is used, especially when layout is important within the region.

The apex_javascript.add_onload_code starts the animation of the carousel. The carousel switches panels every 3 seconds. This can be adjusted (Pause : 3000).

See also

Oracle APEX Cookbook : Second Edition Create reliable, modern web applications for desktop and mobile devices with Oracle Application Express with this book and ebook
Published: October 2013
eBook Price: $35.99
Book Price: $59.99
See more
Select your format and quantity:

Creating a dynamic action plug-in

A dynamic action is a piece of code that can handle page events (onchange, onclick, and so on). It is actually the APEX implementation of JavaScript event handling. For example, you can show or hide an item or a region at a specific moment. And that moment can be, for example, when a user clicks on an item with the mouse, or when a user enters some text in an item. These moments are called events. There are several events which we already described in the Controlling the display of regions and items with Dynamic Actions .

A dynamic action plug-in offers the same functionality, but you can customize the appearance of the affected objects. In this recipe we will show you how you can make a dynamic action plug-in which changes the color of a text item when a user enters some text in another text item.

Getting ready

No preparations needed, except that you should have an existing page with a region where you can put the items from this recipe.

How to do it...

Follow these steps:

  1. In the Application Builder , go to Shared Components | Plug-ins .
  2. Click on the Create button.
  3. In the Name section, enter a name for the plug-in, for example, setcolor.
  4. In the Internal Name text field, enter a unique name, for example, com.packtpub.setcolor. In the Type listbox, select Dynamic Action .
  5. In the Category listbox, select Miscellaneous (use this category to easily find the plug-in back in the categorized action listbox, explained later on in the recipe).
  6. In the Source section, enter the following code into the PL/SQL Code text field:

    function render_setcolor ( 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 l_result.javascript_function := 'function(pAction){this.affectedElements.css("color", this.action.attribute01);}'; l_result.attribute_01 :=p_dynamic_action.attribute_01; -- return l_result; end render_setcolor;

    This piece of code starts with the declaration of the function with its parameters. The return value should be of type apex_plugin.t_dynamic_action_render_result. This return type contains the call to the built-in JavaScript function this.affectedElements.css() which can change the style attributes of an object in the web page, in this case a text item. The value of the color is set by the parameter p_dynamic_action.attribute_01.

  7. In the Callbacks section, enter render_setcolor into the Render Function Name text field.
  8. In the Standard Attributes section, check the For Item(s) and the Affected Element Required checkbox.

  9. Click on the Create Plug-in button.
  10. In the Custom Attributes section, click on the Add Attribute button.

  11. In the Name section, enter color into the Label text field.
  12. Click on the Create button.
  13. Click on the Apply Changes button.
  14. The plug-in is ready and now we will create two text items, one for triggering the event, and one that is going to be the affected item.
  15. Go to an existing page where you want to put this.
  16. In the Items section, click on the add icon.
  17. Select Text Field .
  18. Enter a name in the text field, for example, PX_EVENT (replace X by the page ID)
  19. Click on Next three times.
  20. Click on the Create Item button to end the Create Item wizard.
  21. Again in the Items section, click on the add icon.
  22. Select Text Field .
  23. Enter a name in the text field, for example, PX_TEXT (replace X by the page ID).
  24. Click on Next three times.
  25. Click on Create Item .
  26. The two items are ready now. The last thing we have to do is to create the dynamic action.
  27. In the Dynamic Actions section in the lower-left corner, click on the add icon.
  28. Select Advanced .
  29. Enter a name for the dynamic action, for example, set_color. Click on Next .
  30. In the Item(s) text field, enter the name of the event item, PX_EVENT (replace X by the page ID).
  31. In the Condition listbox, select equal to .
  32. In the Value text area, enter SEMINAR. Click on Next .
  33. In the Action listbox, select our newly created plug-in, setcolor[Plug-in] .

  34. In the Color text field, enter a color, for example, blue. Click on Next .
  35. In the False Action listbox, again select the new plug-in, setcolor[Plug-in] .
  36. In the Color text field, enter another color, green. Click on Next .
  37. In the Selection Type listbox, select Item(s) .
  38. Click on the item PX_TEXT (replace X by the page ID) and click on the single right arrow in the middle of the shuttle. Click on the Create Dynamic Action button.

You are ready now. Run the page and see what happens when you enter SEMINAR in the Event text field.

How it works...

This dynamic action plug-in works just as the normal dynamic actions, except that there is a new action. Instead of show or hide, we now give the affected object a certain color, simply by changing the style of the object. We could have used some other styles, for example, font-weight instead of color. In that case, don't use the color names (blue and green), but use bold and normal.

Creating a process type plug-in

A process type plug-in extends the functionality of a page process. This can be anything, but it is typically used for APEX built-ins or Internet functionalities like e-mail sender or Twitter update. The benefit of this is that the process type plug-ins can be reused. We will create a process type plug-in which changes the language by using the apex_util.set_session_lang built-in. There are more ways to change the session language, but in this recipe we will use this built-in in a page process to demonstrate how it works.

Getting ready

Make sure you have an existing web page with a region.

How to do it...

Follow these steps:

  1. Go to Shared Components and click on Plug-ins .
  2. Click on the Create button.
  3. In the Name section, enter set_language in the Name text field.
  4. In the Internal Name text field, enter a unique name, for example, com.packtpub.set_language.
  5. In the Type listbox, select Process .
  6. In the PL/SQL Code text area, enter the following code:

    function set_language ( p_process in apex_plugin.t_process, p_plugin in apex_plugin.t_plugin ) return apex_plugin.t_process_exec_result is --Dynamic Attribute mapping l_language varchar2(50) := p_process.attribute_01; l_result apex_plugin.t_process_exec_result; begin --Set session language apex_util.set_session_lang(l_language); --Set success message l_result.success_message := 'Session language switched to'||l_language; return l_result; end set_language;

    The function starts with two arguments, which are necessary, but have a default value. The return type is apex_plugin.t_process_exec_result. The actual switch Is done by apex_util.set_session_lang.

  7. In the Callbacks section, enter set_language in the Execution Function Name .
  8. Click on the Create Plug-in button.
  9. In the Custom Attributes section, click on the Add Attribute button.
  10. In the Name section, enter language in the Label text field.
  11. Click on the Create button. The process type plug-in is ready. Now we will create a text item and a button to start the process.
  12. Go to your application and click on the page you want to edit.
  13. In the Processes section, click on the add icon.
  14. Select Plug-ins .
  15. Select the plug-in we just created, set_language .
  16. Enter a name for this plug-in, for example setlang. Click on Next .
  17. In the Language text field, enter &PX_LANGUAGE (replace X by the page ID).
  18. Click on the Create Process button.
  19. In the Items section, click on the add icon.
  20. Select the Select List option.
  21. Enter PX_LANGUAGE (replace X by the page ID) in the Item Name text field.
  22. In the Region listbox, select the region you want to put this item on. Click on Next two times.
  23. In the Create Item section, set the Page Action when Value Changed listbox to Submit Page . Click on Next .

  24. Click on the Create or edit static List of Values link.

  25. In the pop-up window, enter the following languages in both columns:

  26. Click on the Apply button.
  27. Click on Next .
  28. Click on the Create Item button.

The process type plug-in and the page are ready now. Run the page and test the plug-in.

The only thing this plug-in does is a call to apex_util.set_session_lang with a language abbreviation.

See also

Creating an authorization plug-in

In Version 4.1, the authorization plug-in was introduced. The advantages of plug-ins are mostly reusability and declarative setup. To demonstrate the use of an authorization plug-in, we will create a page and a tab that will only be displayed when the logged user has the correct privilege, that is ADMIN. This privilege is stored in the APP_USERS table. When the user logs in and he or she has no correct privilege (ADMIN), the tab will not be displayed. On top of that, when the user tries to access that page by modifying the URL (with the concerned page number), an error message will be displayed.

Getting ready

Make sure you have access to an existing application and the APP_USERS table and the APP_COUNTRIES table.

How to do it…

Follow the given steps to create the plug-in:

  1. Go to Shared Components .
  2. In the User Interface section, click on Plug-ins .
  3. Click on Create .
  4. In the Name text field, enter is_admin.
  5. In the Internal Name text field, enter com.packtpub.is.admin.
  6. In the Type listbox, select Authorization Scheme Type .
  7. In the PL/SQL Code text area, enter the following code:

    function is_admin (p_authorization in apex_plugin.t_authorization ,p_plugin in apex_plugin.t_plugin) return apex_plugin.t_authorization_exec_result is cursor c_usr (b_role in varchar2) is select 1 from app_users where username = p_authorization.username and role = b_role; -- r_usr c_usr%rowtype; l_usr_found boolean; l_role varchar2(4000) := p_authorization.attribute_01; l_result apex_plugin.t_authorization_exec_result; begin open c_usr(l_role); fetch c_usr into r_usr; l_usr_found := c_usr%found; close c_usr; -- if l_usr_found then l_result.is_authorized := true; else l_result.is_authorized := false; end if; -- return l_result; end is_admin; [9672_5_1.txt]

  8. In the Callbacks section, enter is_admin in the Execution Function Name text field.
  9. Click on Create Plug-in .
  10. In the Custom Attributes section, click on the Add Attribute button.
  11. In the Label text field, enter Role.
  12. Click on Create .

Next, we will create the authorization scheme in the following steps:

  1. Go to Shared Components .
  2. In the Security section, click on Authorization Schemes .
  3. Click on Create .
  4. Click on Next .
  5. In the Name text field, enter is_admin.
  6. In the Scheme Type listbox, select is_admin [Plug-in] .
  7. In the Role text field, enter ADMIN.
  8. In the Identify error message displayed when scheme violated (Value Required) text area, enter Only administrators have access to this page.
  9. Click on Create Authorization Scheme .

Now we have created the plug-in and the authorization scheme. We will create the form and the tab in the following steps:

  1. In the Application Builder , click on the Create Page button.
  2. Click on the Form icon.

  3. Click on the Form on a table with Report icon.
  4. Enter a page name and a region title. Click on Next .
  5. In the Table / View Name listbox, select APP_COUNTRIES . Click on Next .
  6. Select Use an existing tab set and create a new tab within the existing tab set .
  7. In the Tab Set listbox, select an existing tab set.
  8. In the New Tab Label text field, enter the name of the new tab, that is Maintain Countries. Click on Next .
  9. Click on Next .
  10. Click on Next .
  11. Enter the Page Name and the Region Title for the form, that is Maintain Countries.
  12. Click on Next .
  13. Select Select Primary Key column(s) .
  14. In the Primary Key Column 1 listbox, select ID .
  15. Click on Next .
  16. Click on Existing Sequence .
  17. In the Sequence listbox list, select CTR_SEQ . Click on Next .
  18. In the next step, transfer all available columns to the right-hand side panel. Click on Next .
  19. Click on Next .
  20. Click on Create .
  21. Click on Edit Page.
  22. In the Page Rendering section, click on the Authorization link.

  23. In the Authorization Scheme listbox, select IS_ADMIN .
  24. Click on Apply Changes .
  25. Now the authorization step is only done for the report, not for the form, so you still have to do that in the same way as described in the previous steps.
  26. Go to Shared Components .
  27. In the Navigation section, click on Tabs .
  28. Click on the Maintain Countries tab.
  29. In the Authorization section select IS_ADMIN in the Authorization Scheme listbox.
  30. Click on Apply Changes .

Run the application. When logged in with the ADMIN role, the user will see the Maintain Countries tab, and the user can click on the tab to access the page. The user can even access the page by modifying the URL. However, if the user hasn't got the necessary privilege, the tab will not be visible at all, and when trying to access the page via the URL, the user will get an error message.

How it works...

In the plug-in, the query checks whether the user with the ADMIN role appears in the APP_USERS table. If so, true is returned, otherwise, false is returned.

To make use of the plug-in, it needs to have the following parameters:

Name

Type

p_authorization

apex_plugin.t_authorization

p_plugin

apex_plugin.t_plugin

And the return value needs to be of type apex_plugin.t_authorization_exec_result.

The t_authorization type contains the following attributes:

Attribute

Datatype

Description

id

NUMBER

ID

name

VARCHAR2(255)

Name of the authorization scheme

username

VARCHAR2(255)

Username of the current user

attribute_01

VARCHAR2(32767)

Attribute value 1

attribute_02

VARCHAR2(32767)

Attribute value 2

...

...

...

attribute_15

VARCHAR2(32767)

Attribute value 15

There's more…

The authorization scheme has a default evaluation point of once per session. This means that if you change the role in the APP_USERS table, the user will only see the change when he or she first logs out and in. You can change the evaluation point to once per page view, which means that a change in the APP_USERS table will be in effect when the user re-queries the page. You can change the evaluation point in the following way:

  1. Go to Shared Components .
  2. Click on the concerned authorization scheme, in this case is_admin .
  3. In the Evaluation Point section, click on the Once per page view radio button.

Summary

This article described five types of plug-ins: Item type, Region type, Dynamic Action type, Process type, and Authorization type. It also discussed how to create and use them.

Resources for Article :


Further resources on this subject:


Oracle APEX 4.0 Cookbook Over 80 great recipes to develop and deploy fast, secure, and modern web applications with Oracle Application Express 4.0 with this book and eBook
Published: December 2010
eBook Price: $35.99
Book Price: $59.99
See more
Select your format and quantity:

About the Author :


Marcel Van Der Plas

Marcel van der Plas was born in 1969 in Eindhoven and still lives there. He has been an Oracle Consultant for over 15 years. Marcel has worked on many projects with Oracle Designer, Oracle Forms, and Oracle Reports. Later on, he became interested in APEX and did some projects with APEX. Marcel has been working on an APEX project for an electronics company for over 2 years.

Marcel currently works for Ciber. Other companies he worked for are Atos Origin and Whitehorses. For Whitehorses, he wrote some articles (White books) about Oracle.

Marcel wrote the Oracle APEX 4.0 Cookbook, Packt Publishing, with Michel van Zoest. You can find APEX blogposts from Marcel at http://orclapex.blogspot.com. Besides that, you can follow Marcel on Twitter (@whmvdp).

Michel Van Zoest

Michel van Zoest is a consultant with years of experience in building web applications using Oracle technologies such as Oracle Web Forms, Oracle Designer, MOD_PLSQL, ADF, SOA Suite, and of course, APEX.

He is one of the first Oracle Application Express Developer Certified Experts in the world. He has used his APEX knowledge in projects for companies ranging in size from a single employee to large multinationals. His experience in these projects has been used in the realization of this book.

Michel currently works at Whitehorses in the Netherlands and runs his own blog at http://www.aboutapex.com. He also blogs at the company website on http://blog.whitehorses.nl and he regularly writes White book articles (in Dutch) for Whitehorses.

You can reach Michel on Twitter at @mvzoest or e-mail him at michel@aboutapex.com.

Books From Packt


Oracle APEX Best Practices
Oracle APEX Best Practices

Oracle APEX 4.0 Cookbook
Oracle APEX 4.0 Cookbook

Oracle APEX 4.2 Reporting
Oracle APEX 4.2 Reporting

 Oracle Application Express Forms Converter
Oracle Application Express Forms Converter

Oracle Application Express 4.0 with Ext JS
Oracle Application Express 4.0 with Ext JS

Oracle Application Express 3.2 - The Essentials and More
Oracle Application Express 3.2 - The Essentials and More

Oracle SQL Developer 2.1
Oracle SQL Developer 2.1

Mastering Oracle Scheduler in Oracle 11g Databases
Mastering Oracle Scheduler in Oracle 11g Databases


No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
a
z
C
Q
F
3
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software