C H A P T E R  5

Region Plug-Ins

Region plug-ins, as you may guess, allow you to create your own region types in APEX. Before APEX 4.0, if you wanted to create a “custom” region you would need to create a PL/SQL type region that would generate all the content for your custom region. Region plug-ins take a similar approach, and also provide an excellent declarative and supported framework for managing custom region types.

This chapter explains what region plug-ins do and don't cover, helps you build a region plug-in, and introduces AJAX functionalities. The plug-ins covered in previous chapters (item and dynamic action) also support AJAX functionality, so the AJAX content in this chapter is relevant to the previous two plug-in types as well.

Background on Regions and AJAX

Before developing a region plug-in with AJAX support, it's important to cover two things: the architecture of a region (i.e., the difference between the region itself and a region template) and AJAX in APEX. It is important to understand these topics before developing the region plug-in and adding in AJAX functionality.

Regions

The easiest way to explain the architecture of a region is by analyzing one. Figure 5-1 shows the My Form region that you created in the previous chapter. The content inside the dotted line is part of the region's body. The content outside the dotted line is part of the region template. Region plug-ins only generate content for the region body and they don't need to be concerned with the region template. The region template will wrap the region body with the standard display code, which is determined by the APEX developer.

Figure 5-1. Region body outline

Another way to view the difference between the region content and the template is to examine the region template. Region templates define the look and feel of the region. To view the region template

1. Go to the application's Shared Components.
2. Under the User Interface, click on the Templates link as shown in Figure 5-2.
   

   Figure 5-2. Templates link in Shared Components

3. Filter the templates report by setting the Type list to Region.
4. Click on the default region. The default region has a check mark in the Default column. Figure 5-3 shows the default region template in the application as Reports Region.
   

   Figure 5-3. Default region template

5. On the Edit Region Template page, scroll down to the Definition region. Figure 5-4 shows the content of the Template text area.
   

   Figure 5-4. Region template definition

In Figure 5-4, you'll notice that there are some HTML tags that wrap the content of the region. These are some special tags that APEX will replace with the appropriate region attributes such as #TITLE# and the button tags (#CLOSE#, #PREVIOUS#, … ,#HELP#). The #BODY# substitution string is what will be replaced with the content from the region plug-in.

Because the region plug-in handles only the “meat” of the region, region plug-ins need only to focus on what is necessary to be displayed as part of the region. You don't need to be concerned about styling the region, displaying the region buttons, and so on, since the region template handles all these elements.

AJAX

At a very high level, AJAX allows the browser to send data to the server and receive a response back from it without having to submit the page. With respect to APEX, this means that you can send some data to APEX, run a block of PL/SQL code, and send data back to the browser without having to submit the page.

Prior to APEX 4.0, AJAX functions were handled through an On Demand application process. Though it is not required, building an AJAX function using the old (pre-APEX 4.0) method may help you understand and appreciate how the new plug-in AJAX function works. The following steps cover how to build and use a simple AJAX function the “old way.” This function will send the user's current value to APEX and return the value multiplied by two.

1. Create a new blank page with the following attributes:

   Page Number: 30
   Name:AJAX (Old)
   HTML Region 1: My Region
   Tab: AJAX(Old)

2. Edit the new page, Page 30, and create a new page item in My Region with the following attributes:

   Item Type: Number Field
   Item Name: P30_X

3. Create a region button with the following attributes:

   Button Name: Run AJAX
   Button Alignment: Left
   Action: Defined by Dynamic Action

   
   

   If you run Page 30, it should now look like Figure 5-5.

   

   Figure 5-5. AJAX demo page

4. Go to Shared Components and click on the Application Processes link as shown in Figure 5-6.
   

   Figure 5-6. Application Processes link in Shared Components

5. In the Application Processes window, click the Create button.
6. On the Identification wizard page, enter the values as shown in Figure 5-7. Setting the Point to On Demand… allows this process to be accessible via an AJAX call. Click the Next button to go to the next step.
   

   Figure 5-7. Create Application Process > Identification

7. On the Source page, enter the following PL/SQL code in the Process Text text area. This is the code that will be run when the AJAX function is triggered by the browser. Click the Next button to continue.

   In the code, apex_application.g_x01 is a value that will be passed from the AJAX JavaScript call to APEX. APEX supports up to ten values (apex_application.g_x01 .. apex_application.g_x10) along with one clob value (apex_application.g_clob_01).

   The PL/SQL code “sends” a value back to the client's browser by printing the value with the htp.p call. JavaScript will interpret this value as a string that will need to be converted accordingly.

   -- Takes value and multiplies it by 2
-- No error handling etc, as this is a demo
DECLARE
  v_num pls_integer;
BEGIN
  v_num := to_number(apex_application.g_x01);

  v_num := v_num * 2;

  htp.p (v_num);
END;
8. On the Conditionality page, leave the default options (i.e., no condition) and click the Create Process to complete the wizard.
9. The final thing to do is to write the JavaScript code that will trigger the AJAX call. Edit Page 30 and right click on the RUN_AJAX button. Select the Create Dynamic Action option from the context menu.
10. In the Identification section, set the Name to Run AJAX Function. Click the Next button to continue.
11. Figure 5-8 shows the default options on the When page. Leave these settings and click the Next button.
    

    Figure 5-8. Create Dynamic Action > When

12. On the True Action page, set the Action to Execute JavaScript Code. Uncheck the Fire On Page Load check box. Enter the following JavaScript code in the Code text area. Click the Next button to continue.
    
    

    In the JavaScript code below, you'll notice that the first line of code references the AJAX_DEMO application process.
    
    

    The function addParam defines the x01..x10 values that will set the PL/SQL apex_application.g_x01 .. apex_application.g_x10 variables as part of the AJAX request.

    // Demo code for AJAX calls
var ajax = new htmldb_Get(null,$v('pFlowId'), 'APPLICATION_PROCESS=AJAX_DEMO',0);

// Value to send to PL/SQL code
// Note: this does not "submit" P30_X (that can be done but in another way)
ajax.addParam('x01', $v('P30_X'));

// Trigger AJAX call (will send POST to APEX)
var ajaxResult = ajax.get();

// Display the result in an alert window
window.alert(ajaxResult);

    a.

    b.

13. On the Affected Elements page, click the Create button to finish the wizard.
14. Run Page 30. Enter 2 in the text box and click the Run Ajax button. An alert window should pop up with the value 4, as shown in Figure 5-9.
    

    Figure 5-9. Run AJAX result

If you open the Console window, you'll see the POST request that the browser made to the server. Figure 5-10 shows the result from the POST request. From the console result, you can clearly see how the values are sent to the server. Figure 5-11 shows the response back from the server. As previously mentioned, this result is a simple string in JavaScript. If you need to do anything with it, you'll need to explicitly convert it to the correct data type. In this example, you'd need to convert it to a number.

Implementing AJAX functionality via a plug-in is much easier to do than the process just described. In the region plug-in example to follow, you will create an AJAX function and you should be able to see the common features with this example.

Figure 5-10. AJAX POST request

Figure 5-11. AJAX POST response

Example Business Problem

As with the other plug-ins, the first thing you should do is state your business requirements. This region plug-in should display the titles from an RSS feed. The plug-in should also implement some additional related functionality. The following is the complete list of requirements:

• Display a list of RSS feed titles.
• Configure the maximum number of RSS feeds in the region, ranging from 5, 10, and 15 items.
• Needs to currently support RSS feeds from Blogger (www.blogger.com).
• When a user clicks on an RSS title, a modal window appears and displays the content of the RSS feed. The default modal window size will be configurable.

The plug-in you are going to build will use some of the UTL_HTTP features in Oracle to obtain RSS feeds. HTTP access and other network services are potential security vulnerabilities, so their access is restricted in Oracle Database 11g and higher. You will need to enable network services and grant access to them in order to create the plug-in described next.

Think twice about enabling UTL_HTTP access in a production environment. Discuss such changes with your database administrator. Be sure that you do not violate any security policies. The example to follow is meant for demonstration purposes and should be thoroughly reviewed before implementation in a production environment.

The following are the assumptions made in describing the process of enabling the UTL_HTTP access needed by this chapter's example plug-in:

• The current user that the APEX application is being run as (i.e., parsing schema) is the APRESS user. In the scripts and queries below, substitute APRESS for your user.
• Unless explicitly specified, scripts and queries will be run as the SYSTEM or SYS user. You may need to ask your DBA to run these scripts for you.

All the scripts are in the files included with this book. If your environment is not as described in the preceding list, you will need to modify the scripts before executing them. For example, you may need to substitute in the user name that you are using.

When you have the scripts ready for your environment, follow these steps to enable UTL_HTTP access:

1. Run the following, which will grant access to external networks for your current user. Don't forget to change the value of v_user to your username.
   -- Run as SYSTEM or SYS
-- Creates a ACL with access to all domains and ports
-- Or leverages one that already exists
DECLARE
  v_acl dba_network_acls.acl%TYPE;
  v_user VARCHAR2(30) := 'APRESS'; -- *** CHANGE TO YOUR USER
  v_cnt pls_integer;
BEGIN
  v_user := upper(v_user);

  -- Get current ACL (if it exists)
  SELECT max(acl)
  INTO v_acl
  FROM dba_network_acls
  WHERE host = '*'
    AND lower_port IS NULL
    AND upper_port IS NULL;

  IF v_acl IS NULL THEN
    -- No ACL exists. Create one
    v_acl := 'apress_full_access.xml';

    -- Create ACL with access to your user
    dbms_network_acl_admin.create_acl (
      acl          => v_acl,
      description  => 'ACL Access for Apress demo',
      principal    => v_user,
      is_grant     => TRUE,
      privilege    => 'connect',
      start_date   => NULL,
      end_date     => NULL);

    -- Grant access to ACL to all ports and ports
    dbms_network_acl_admin.assign_acl (
      acl         => v_acl,
      host        => '*', -- This is the network that you have access to.
      lower_port  => NULL,
      upper_port  => NULL);
  ELSE
    -- ACL Exists, just need to give access to user (if applicable)
    SELECT count(acl)
    INTO v_cnt
    FROM dba_network_acl_privileges
    WHERE acl = v_acl
      and principal = v_user;

    IF v_cnt = 0 THEN
      -- User needs to be granted
      dbms_network_acl_admin.add_privilege(
        acl       => v_acl,
        principal => v_user,
        is_grant  => true,
        PRIVILEGE => 'connect'),
    ELSE
      -- User has access to network
      -- Nothing to be done
      NULL;
    END IF;

  END IF;

  COMMIT;

END;
/
2. Execute the following queries to confirm that the ACL setup worked. You should see your user associated to the network ACL with full access.
   -- All ACLs
SELECT host, lower_port, upper_port, acl
FROM dba_network_acls;

-- Privileges for ACLs
-- Lists which users have access to which ACL
SELECT acl, principal, privilege, is_grant, invert, start_date, end_date
FROM dba_network_acl_privileges;
3. Confirm that your user now has network access by running the following script, with DBMS_OUTPUT enabled as your current user. You should see “Ok. Have access” as part of the output.
   -- Test that user has network access now
-- Run as APRESS user
-- Determines if current user has access to external connections
-- Makes a simple connection to www.google.com on port 80
-- Result will be in DBMS_OUTPUT
DECLARE
  v_connection  utl_tcp.connection;
BEGIN
  v_connection := utl_tcp.open_connection(remote_host => 'www.google.com', remote_port => 80);
  utl_tcp.close_connection(v_connection);

  dbms_output.put_line('Ok: Have Access'),

  EXCEPTION
    WHEN others THEN
      IF sqlcode = -24247 THEN
        -- ORA-24247: network access denied by access control list (ACL)
        dbms_output.put_line('No ACL network access.'),
      ELSE
        dbms_output.put_line('Unknown Error: ' || sqlerrm);
      END IF;
END;
/

If you see the message “Ok. Have access,” then all is well. Proceed with creating the example plug-in.

Building the Region Plug-in

Now that the business requirements have been defined, you can start creating the region plug-in. Similar to the dynamic action plug-in example in the preceding chapter, some steps will not be covered on a step-by-step basis as they have already been covered previously.

Initial Configuration and Setup

To start building a region plug-in, create a new plug-in with the attributes listed below. Once you are finished, click the Create button to save the plug-in.

Name: ClariFit RSS Reader

Internal Name: COM.CLARIFIT.APEXPLUGIN.RSS_READER

Type: Region

Next, create a directory to store and reference external web files. This will allow you to easily make modifications as you build your plug-in. Here are the steps:

1. Create a directory called c:wwwRSSReader
2. Modify the plug-in. In the Settings region set the File Prefix to http://localhost/RSSReader/
3. Click the Apply Changes button to save your changes.

Scroll down to the Standard Attributes section and check off the has "Escape Special Characters" Attribute option as shown in Figure 5-12. Click the Apply Changes button to save your change. In this plug-in, the Escape Special Characters attribute will be used to escape the RSS feed content (if enabled in region). The RSS feed URL will be defined by a custom attribute rather than the region source.

Figure 5-12. Region plug-in standard attributes

Since this plug-in does not require a traditional “Region Source,” such as an SQL query or some plain text, you do not need to check those boxes off. If you create a plug-in that requires the user to enter a SQL query as the region source, you can parse the query using the APEX_PLUGIN_UTIL.GET_DATA and APEX_PLUGIN_UTIL.GET_DATA2 function. For more information, please refer to the APEX API documentation.

Custom Attributes

The following are the custom attributes that the plug-in will use. These attributes are based on the requirements. Specify the attributes for the region using the dialog shown in Figure 5-14, following the list.

• Scope: Component

  Attribute:1
  Label: RSS Type
  Type: Select List
  Required: Yes
  Default Value: Blogger

• LOVs:

  Display Value: Blogger
  Return Value: Blogger

  For now, Blogger will be the only support RSS feed. If you want to support additional RSS feeds, you can modify this list and the code accordingly.

• Scope: Component

  Attribute: 2
  Label: RSS URL
  Type: Text
  Required: Yes
  Display Width: 50

• Scope: Component

  Attribute: 3
  Label: Max Rows
  Type: Select List
  Required: Yes
  Default: 5

• LOVs:

  Display Value: 5
  Return Value: 5
  
  Display Value: 10
  Return Value: 10
  
  Display Value: 15
  Return Value: 15

• Scope: Component

  Attribute: 4
  Label: Modal Width(controls width of the modal window)
  Type: Integer
  Required: Yes
  Display Width: 3
  Maximum Width: 4
  Default Value: 700

• Scope: Component

  Attribute: 5
  Label: Modal Height(controls height of the modal window)
  Type: Integer
  Required: Yes
  Display Width: 3
  Maximum Width: 4
  Default Value: 400

You should feel comfortable with and understand the impacts of adding and modifying custom attributes by now. The only difference that you'll experience with region plug-in custom attributes is how they are displayed on the region's edit page.

Instead of being displayed in the usual Settings section, as shown in Figure 5-13, a new tab called Region Attributes contains the custom attributes. Figure 5-14 shows this new tab when modifying a region that is a plug-in region with custom attributes.

Figure 5-13. Dynamic action plug-in custom attribute settings

Figure 5-14. Region plug-in custom attribute settings

Creating a Test Page

Before creating the render and AJAX functions, you should set up a test page to help view your changes. The following steps create a test page and a region that uses the new region plug-in:

1. Create a new page with Page Type of Plug-ins. Click the Next button.
   
   

   Just to clarify, there's no such thing as a Page plug-in. In this case, plug-in refers to a region plug-in.

   
   
2. In the Type page, select ClariFit RSS Reader as the Plug-in. Click the Next button.
3. On the Page and Region Attributes page, set the following values, then click the Next button to continue.
   
   

   Page Number: 40
   Page Name: RSS Reader
   Region Name: RSS Reader

4. On the Tab Options page, click the Use an existing tab set and create a new tab within the existing tab set radio button. In the New Tab Label field, enter RSS Reader. Click the Next button to continue.
5. On the Settings page, leave the default options but set the RSS URL to http://www.talkapex.com/feeds/posts/default, as shown in Figure 5-15. Click the Next button to continue.
   
   

   (Note: You can use any Blogger URL by replacing www.talkapex.com with your URL.)

   

   Figure 5-15. RSS Reader settings

6. On the confirmation page, click the Finish button to create the page.

At this point, if you run Page 40, it will display an error message since you have not defined or created a render function, as shown in Figure 5-16. The next section will define and create the region render PL/SQL function.

Figure 5-16. No render function error message

Creating the Render Function

Just like the other plug-ins, this plug-in will store its PL/SQL code in the pkg_apress_plugins package. To start, get the region plug-in render function template and paste it into pkg_apress_plugins spec. Name the render function as f_render_rss_reader. Your pkg_apress_plugins package specification should now look like Figure 5-17.

Figure 5-17. pkg_apress_plugins.f_render_rss_reader Package Spec

The next thing you'll need to do is register the render function with the plug-in. Edit the plug-in and scroll down to the Callbacks region. Set the Render Function Name to pkg_apress_plugins.f_render_rss_reader, as shown in Figure 5-18.

Figure 5-18. Region plug-in callbacks

Modify the package body for pkg_apress_plugins and add the following code at the bottom of code.

The following is a description of the preceding code that is keyed to the line numbers:

349-354: Define the plug-in's attributes and use meaningful variables. All the attributes are strings that need to be explicitly converted to appropriate PL/SQL data types when applicable.

365-390: Reusable internal procedure to display each of the RSS titles in a table format. The titles include links that will trigger some JavaScript code to display the RSS content in a modal window. This will be used to make an AJAX call

395-400: Minimal debug information. Always include some debug information in your plug-in.

402-449: Contains code that is only applicable in normal display mode. The code is there to support the display of the RSS content in a modal window. If the page is run in print mode, then this code is not required.

Line 404 references a JavaScript file that has yet to be created. You will create this file when implementing the AJAX support.

When developing plug-ins with AJAX support, you may tend to initially focus on getting the region to display what you want to display and then add the additional code.

439: This line is very important for AJAX calls. The key component is the reference to the apex_plugin.get_ajax_identifier function.

In the AJAX example at the beginning of the chapter, the JavaScript code referenced the PL/SQL code to run by identifying the application process AJAX_DEMO. Plug-ins need a similar identifier/reference. The APEX plug-in APIs make things simple so that you don't need to worry about naming this identifier. The apex_plugin.get_ajax_identifier function provides a unique name.

451-472: Handle RSS type-specific code to obtain the RSS title and some meta data. Lines 475-476 handle what happens if an unknown RSS type is defined. In this case, it displays a simple error message. How you handle errors is entirely up to you, depending on your business needs. You can use a “soft” error message (as in this case) or a more “harsh” error messages (i.e., raise an application error).

If you run Page 40, it should look like Figure 5-19. Note the values for the RSS feed may vary depending on the URL. If you click on any of the titles, nothing happens as the JavaScript still hasn't been added and the AJAX function has not been defined. This will be covered in the next section.

If you discard the JavaScript specific code, the code for this plug-in is pretty simple and straight forward. The primary responsibility for a region plug-in is to display some content. You don't need to be concerned about items and buttons attached to the region as they are handled as part of the standard APEX region process.

Figure 5-19. RSS Reader rendered

Creating the AJAX Function

This section will add AJAX support to the plug-in. Though this example is for a region plug-in, the concept is the same for other plug-ins that support AJAX calls. Because AJAX involves both server side code (handled by PL/SQL for APEX) and JavaScript code, this section will cover both sets of code.

JavaScript

When working with code that links PL/SQL with JavaScript (and vice versa), it can be difficult to determine whether to start with the client side code (JavaScript) or the server side code (PL/SQL). When dealing with AJAX functions, it is sometimes easier to start with the JavaScript portion. Once the base JavaScript code is working, you start working on the server code. This is usually an iterative process, modifying both JavaScript and the PL/SQL code.

The JavaScript code will use the Console Wrapper JavaScript instrumentation package. To that end, copy $console_wrapper_1.0.3.js into in c:wwwRSSReader. Then create an empty file named clarifitRSSReader_1.0.0.js in c:wwwRSSReader. This is the same name that was used in the render function. Open the file and paste in the following code:

The following is a description of the preceding code that is keyed to the line numbers:

1 & 74: Like other JavaScript code, this block of JavaScript explicitly defines the jQuery namespace but leverages the version of jQuery that is part of APEX.

26-30: Displays a “Loading...” message when the user clicks on a RSS title and is waiting for the server to respond.

32-36: This is what actually makes the AJAX call. This code is very similar to the example code covered in the Background > AJAX section at the beginning of this chapter. The major difference is that on line 33, instead of referencing an application process by APPLICATION_PROCESS, it references the plug-in process by PLUGIN. The name of the plug-in AJAX identifier is defined in the region's render function with a call to apex_plugin.get_ajax_identifier (refer back to the render function).

38: The response from the server comes back as a string. Since it is really a JSON object, you need to explicitly convert it to a JavaScript JSON object. If you are expecting a non-string value, you will always need to explicitly convert it.

41-67: Displays the RSS content (received from the AJAX call) in a modal window or the error message accordingly.

Refresh Page 40 and click on one of the RSS links. Look in the console window and you should see the POST request, as shown in Figure 5-20. You can see the values that are passed to APEX (x01 and x02) that will be used in your PL/SQL AJAX render function.

If you click on the Response tab, you'll see that a bunch of HTML was returned. Scanning through the HTML, you'll notice that the content is essentially a standard error page in APEX. The error message is “No AJAX function has been defined for plug-in PLUGIN_COM.CLARIFIT.APEXPLUGIN.RSS_READER,” as shown in Figure 5-21. This makes sense as you still have not defined an AJAX function for the plug-in. If you ever get a similar response while developing AJAX support for a plug-in, it helps to scan through the returned HTML to see what is going wrong.

Figure 5-20. AJAX POST request

Figure 5-21. AJAX error message

Writing the AJAX Callback Function

Now that the JavaScript code is complete and “talking” to APEX, it's time to define the server side code. The first thing is to do is create the function specification and register it with the plug-in:

1. Edit the plug-in and scroll down to the Callbacks region. Click on the AJAX Function Name label to view the help text. Similar to render functions, AJAX function header templates are provided in the help text. Copy the function header for region type plug-ins as shown in Figure 5-22.
   

   Figure 5-22. AJAX function help

2. Paste the function template into the package spec for pkg_apress_plugins. Name the function f_ajax_rss_reader and compile the package spec.
3. To register the function with the plug-in, edit the plug-in and scroll down to the Callbacks section. Enter pkg_apress_plugins.f_ajax_rss_reader in the AJAX Function Name field. Click the Apply Changes button to save your change.

The final step is to enter the code for the package body. Edit the package body for pkg_apress_plugins and copy the following code at the bottom of the package:

The following is a description of the preceding code that is keyed to the line numbers:

491-493: Meaningful variable names for values passed in as part of POST request. Remember these variables have nothing to do with plug-in specific attributes.

495-496: Plug-in specific variables.

505: The return object contains a dummy attribute. The only thing to really “return” is what is printed back using htp.p calls.

510-544: Reusable function to print out a JSON object with all the applicable data that the JavaScript function will use to display the RSS content in a modal window. This function is essentially what sends data back to the client's browser.

524-527: Escapes special characters from the RSS content based on the region's escape option. This will play a factor in how the content is displayed to the user. You will see exactly how this impacts the application when testing the plug-in.

546-557: Wrapper function to handle errors. In this example, errors will be handled by the JavaScript function. How you handle AJAX errors is your decision; however, you should make sure that that the application is still useable.

559-607: Code to obtain the contents of an RSS feed.

Testing the Plug-in

The final thing to do is test the final product. Refresh Page 40. It should look like it did in Figure 5-19. If you click on one of the RSS titles, a modal window will appear and display the content from the RSS feed, as shown in Figure 5-23.

Figure 5-23. RSS feed content

The first thing that stands out in Figure 5-23 is that the content shows all the HTML tags rather than being in a human readable format. This is because of the region's Escape Special Characters option, which is currently set to its default value: Yes.

To change this option (and you should only do so if the RSS feed is from a trusted source), edit the region and scroll down to the Security section. Set the Escape Special Characters to No, as shown in Figure 5-24. Run Page 40 and click on the same link as before. The content is a lot more human readable now, as shown in Figure 5-25.

Figure 5-24. Region security settings

Figure 5-25. RSS feed content (unescaped)

Summary

This chapter provided some background information to help you understand what is required for a region plug-in and how AJAX works in APEX. You also built a region plug-in that contained an AJAX function.