The interface used to create APEX plug-ins is accessed under the Shared Components menu of the Application Builder. The plug-in builder interface is accessed via the Plug-ins link on the User Interface section. When you first enter the Plug-ins builder, as shown in Figure 12-1, you will notice that APEX 4.0 is delivered with no plug-ins. There is, however, a button on the page titled "View Plug-in Repository," which will direct you to a location on Oracle's corporate web site that houses plug-ins that are freely downloadable. We will explore this site later in this chapter, but for now we will focus on the mechanics of building a plug-in from scratch.

Figure 12.1. Plug-ins builder home page

We'll start by creating a simple item type plug-in, as it is the easiest to complete and illustrates most of the mechanics of the plug-in architecture. To create a plug-in of any kind, you have to first decide what its purpose will be. In this example, we'll create a text item that will require a value and will have a red background until a value is entered. After at least one character is entered in the field, the background will return to standard white. We'll call this plug-in requiredInColor.

To get started, we need to take a look at the plug-in builder. When you click on the Create button, the plug-in builder page is displayed as shown in Figure 12-2. We filled in the Name, Internal Name, and Type fields in the figure to illustrate how plug-ins should be named. Following are guidelines on plug-in naming best practices:

These guidelines guarantee that your plug-in's name will not be a duplicate of one that you download from another site. They do not ensure that names for plug-ins you create are unique within your organization, so you'll have to manage that on your own. You'll notice that any plug-ins you download from Oracle's plug-in repository have names that are prefixed with com.oracle.apex.

Figure 12.2. Plug-ins builder page

In the Subscription section of the plug-in builder, the Reference Master Plug-in From field allows you to use a copy of an existing plug-in by either entering the name or selecting it from a pop-up list of values. If you leave this field blank, by default the plug-in is considered a master. We will leave this field blank since we are creating a new plug-in.

The File Prefix, #PLUGIN_PREFIX#, is a virtual path that determines where any plug-in support files (like JavaScript files, CSS files, and so forth) will be stored. This prefix points to a location in the database. If you are using a separate HTTP server, you can get better performance if you store the supporting files there, as opposed to on the database. You can either create a new substitution string pointing to a new virtual directory or just use the #IMAGE_PREFIX# in place of the #PLUGIN_PREFIX#.

The next section, PL/SQL Code, is where the guts of the plug-in are built. This code is used to do the following:

You can write your code as an anonymous PL/SQL block in the PL/SQL Code section. You can also create your code as a database package and refer to that package from a block in this section. You'll get better performance from the package-based approach.

Each plug-in type must implement a specific interface, known as a render function, which was standardized so that future APEX enhancements do not break existing plug-ins. Since we are talking about item type plug-ins, we'll first take a look at the item type render function shown in Listing 12-1.

function <name of function> (
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

The name of the function is not important, it just has to follow Listing 12-1's specification. The first two parameters in the render function are of type apex_plugin. The name apex_plugin is actually a synonym for the apex_040000.wwv_flow_plugin package. This record type contains attributes that allow you to control the operation of the item on which the plug-in is being built. The ID attribute, for example, is the HTML ID of the item that can be used in JavaScript to manipulate the Document Object Model (DOM). Listing 12-2 shows an excerpt from the wwv_flow_plugin package showing the definition of the t_page_item and t_plugin record types.

type t_page_item is record
(
    id                          number,
    name                        varchar2(255),
    label                       varchar2(4000),
    plain_label                 varchar2(4000),
    format_mask                 varchar2(255),
    is_required                 boolean,
    lov_definition              varchar2(4000),
    lov_display_extra           boolean,
    lov_display_null            boolean,
    lov_null_text               varchar2(255),
    lov_null_value              varchar2(255),

lov_cascade_parent_items    varchar2(255),
    ajax_items_to_submit        varchar2(255),
    ajax_optimize_refresh       boolean,
    element_width               number,
    element_max_length          number,
    element_height              number,
    element_attributes          varchar2(2000),
    element_option_attributes   varchar2(4000),
    escape_output               boolean,
    attribute_01                varchar2(32767),
    attribute_02                varchar2(32767),
    attribute_03                varchar2(32767),
    attribute_04                varchar2(32767),
    attribute_05                varchar2(32767),
    attribute_06                varchar2(32767),
    attribute_07                varchar2(32767),
    attribute_08                varchar2(32767),
    attribute_09                varchar2(32767),
    attribute_10                varchar2(32767)
)

type t_plugin is record
(
    name         varchar2(45),
    file_prefix  varchar2(4000),
    attribute_01 varchar2(32767),
    attribute_02 varchar2(32767),
    attribute_03 varchar2(32767),
    attribute_04 varchar2(32767),
    attribute_05 varchar2(32767),
    attribute_06 varchar2(32767),
    attribute_07 varchar2(32767),
    attribute_08 varchar2(32767),
    attribute_09 varchar2(32767),
    attribute_10 varchar2(32767)
)

As you can see in the t_page_item record, the name and ID of the item you are creating are available to you via this interface. When you want to operate on the value of your item type plug-in using JavaScript, you can pass the t_page_item.id to a JavaScript function and manipulate the DOM to control the appearance and utility of the item. You can also see that there are ten fields in both record types that start with "attribute." These are custom attributes that you can assign to your plug-in, which can be used to further define your item.

To define the features of your plug-in, you must construct a render function and, optionally, a validation function. The render function defines what the item will do and how it will be displayed. To protect against SQL injection attacks, a validation function should also be added, although it is not required. Listing 12-3 shows the contents of the PL/SQL code that implements our requiredInColor plug-in.

FUNCTION requiredInColor (
  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_name varchar2(30);
  l_result      apex_plugin.t_page_item_render_result;
BEGIN
  IF p_is_readonly OR p_is_printer_friendly THEN
    APEX_PLUGIN_UTIL.print_hidden_if_readonly (
      p_item_name           => p_item.name,
      p_value               => p_value,
      p_is_readonly         => p_is_readonly,
      p_is_printer_friendly => p_is_printer_friendly );
    APEX_PLUGIN_UTIL.print_display_only (
      p_item_name        => p_item.name,
      p_display_value    => p_value,
      p_show_line_breaks => false,
      p_escape           => true,
      p_attributes       => p_item.element_attributes );
  ELSE
    l_name := APEX_PLUGIN.get_input_name_for_page_item(p_is_multi_value=>false);
    HTP.P('<input type="text" name="'||l_name||'" id="'||p_item.name||'"
'||'value="'||htf.escape_sc(p_value)||'" size="'||p_item.element_width||'"
'||'maxlength="'||p_item.element_max_length||'" '||p_item.element_attributes||'
onKeyUp="fldRequired('''||p_item.name||''')" />'),
    APEX_JAVASCRIPT.add_library (p_name=> 'requiredInColor',p_directory =>
p_plugin.file_prefix,p_version => null );
  END IF;
  RETURN l_result;
END requiredInColor;

The code in Listing 12-3 adheres to the requirement shown in Listing 12-2. Following the declaration section, the first thing all plug-ins should do is detect whether the item has been identified as being read-only or printer-friendly. The l_name variable is used to store the name of the item on which the plug-in is based. To get the item name, the following function is called:

l_name := APEX_PLUGIN.get_input_name_for_page_item(p_is_multi_value=>false);

The call to this function includes a parameter, p_is_multi_value=>false. That parameter identifies the page item on which the plug-in is based as a single-value item. If the page item were a select list, for example, the value of the parameter would be set to true. The next two lines of code constitute most of the functionality of the plug-in. The line which begins with HTP.P actually renders the item as an HTML input item.

Notice that the value of the item, p_value, is being "escaped" using the htf.escape_sc() function, which changes values like "<" to "&lt." This function should always be used when passing values from an HTML page, as a malicious user can easily modify input values to submit SQL injection commands.

Paste Listing 12-3's code into the PL/SQL Code section of the plug-in builder and set the Render Function Name in the Callbacks section to the name of the render function from the PL/SQL code. If you forget this step, you will get an error saying that there is no render function for the plug-in when you run a page that contains the item-based plug-in. Figure 12-3 shows the populated PL/SQL Code section along with the correct setting for the Render Function Name.

Figure 12.3. PL/SQL Code section of plug-in builder

Since we want to change the background color of the field as soon as a character is entered, the onKeyUp JavaScript function is called. You can see that the HTP.P function uses onKeyUp to call a JavaScript program called fldRequired. So where is this JavaScript? It's contained within an "included file" called requiredInColor.js that has to be uploaded to a location where APEX can find it.

To keep things simple, we used the #PLUGIN_PREFIX# substitution string so that uploaded files are stored in the database instead of on the HTTP server. The contents of the requiredInColor.js file are shown in Listing 12-4. The file has but one simple function: to change the color of the background of the item ID passed to it depending on whether any text has been entered. The background is set to #FEA5AD, which is a light red color when empty and white when populated. This file is uploaded using the Files section of the plug-in builder, as shown in Figure 12-4.

function fldRequired(fldName)
{
  vValue = document.getElementById(fldName).value;
  if (!vValue)
    document.getElementById(fldName).style.background="#FEA5AD";
  else
   document.getElementById(fldName).style.background="#FFFFFF";
}

Figure 12.4. File Upload section of plug-in builder

Once the JavaScript file is uploaded, the plug-in is ready to be used. Before moving on to using the new plug-in, it is important to discuss how you make changes to the uploaded JavaScript file. It is not as simple as making changes to the file and uploading it again, because APEX 4.0 does not allow the same file to be uploaded more than once. Instead, you have to delete the uploaded file and then re-upload it. While not insurmountable, the process is nothing short of annoying, as you must repeat the change/delete/upload cycle over and over while you're developing and testing your plug-in.

The last step in preparing the plug-in for use is to set the Standard Attributes. In this example, we only need to set the Is Visible Widget attribute, which tells APEX to display items based on this plug-in. If you want any plug-in to be visible, this attribute must be set. Figure 12-5 shows the Standard Attribute settings for this plug-in and the verification that our JavaScript file has been uploaded.

Figure 12.5. Plug-in Standard Attributes

Now that your plug-in has been created, you can include it in any page in your application. It is important to note at this point that the plug-in you just created will only show up on the plug-in home page of the application where it was created. As discussed earlier in this chapter, existing plug-ins can be referenced in the Subscription section of the plug-in builder as opposed to being imported or re-created from scratch. Later in this chapter, we will cover sharing plug-ins by using the export and import features of the plug-in builder.

To test your new requiredInColor plug-in, you need to add it to a page. We modified an update form in the Buglist application. To add the new item type plug-in, edit the page (page 28 in our example) and create a new item. In Figure 12-6, the new item type is set to Plug-in.

Figure 12.6. Creating item type plug-in

In the next step of the process, the installed plug-ins are displayed as shown in Figure 12-7. In our environment, you can see there are several available plug-ins and we have selected Required In Color. This is the name we assigned to our plug-in at the time it was created. The internal name (com.enkitec.requiredInColor) will never show up in a list of available items.

Figure 12.7. Select an existing item type plug-in

From this point on, the item creation process is the same as it would be if you were adding a standard, APEX text item. The only deviation, as we will see shortly, is if you have added custom attributes to your plug-in. In that case, you will have the opportunity to populate those new attributes during the item creation process. Our first plug-in does not contain custom attributes, so the creation process will be very familiar. In Figure 12-8, notice that we are naming the item as normal. The field name is defaulted with a value like P28_X and we modify it to read P28_REQUIRED.

Figure 12.8. Name the new item type plug-in

To actually make this new plug-in-based item useful, we need to associate it with some database column. In the final step of the create item wizard, you would normally choose Database Column as the source type and some existing column as the source. Let's say we want to use this new item for the cost column to show that this column is required. If we assign it to the cost column now, we will get an error at runtime since there is already another item assigned to that column. So for now, leave the Source Type set to the default (Static Assignment), as shown in Figure 12-9. The item will be added to the page and will operate the way we want it to, but the values entered in this item will not be stored in the database.

Figure 12.9. New item type plug-in, unpopulated

When you finish the creation process, run your page. In our case, this means executing a report and clicking the update icon to access the update form that contains our new item type plug-in. The update form, shown in Figure 12-10, contains our new, unpopulated field with a red background (you'll have to take our word for it since this page is monochrome).

The intention of this plug-in was to show the user that there is a field on the page that must contain a value. This is done visually by coloring the background of the page when the field is blank. When we enter a value, as shown in Figure 12-11, the characters show up and the background is changed back to standard white. Remember that our code only checks for a value, any value, and then changes the background color of the field. To make this plug-in more useful, you could further validate the input to ensure it meets the specifications of the system.

Figure 12.10. New item type plug-in, unpopulated

Figure 12.11. New item type plug-in, populated

The intention of this plug-in was to show the user that there is a field on the page that must contain a value. That is done visually by coloring the background of the page item when it is blank. When we enter a value, as shown in Figure 12-11, the characters show up and the background is changed back to standard white.

Remember that this new item doesn't really do anything other than rotate the color of the background. To make this new item actually useful, we need to associate it with a database column so that we can use it just like the current Cost item. To make this happen, a few simple steps are required:

Now when you run the application and put a value in the Cost item, the value will be written to the database when you submit the form. If you do a little testing, you will notice that when the form containing the plug-in-based item displays a record that has a cost value, the item is displayed with a red background. The reason for this is simple. The render function we wrote executes the fldRequired JavaScript function using the onKeyUp event. This event will not be fired when the form is displayed, so we need to add some code that will execute our JavaScript function. Listing 12-5 shows the addition of the APEX_JAVASCRIPT.on_load_code function, which does just what you'd expect it to. The nice thing about this function is that it operates in conjunction with an onLoad script you may be using in the HTML Body of the form.

function requiredInColor (
  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_name varchar2(30);
  l_result      apex_plugin.t_page_item_render_result;

BEGIN
  IF p_is_readonly OR p_is_printer_friendly THEN
    APEX_PLUGIN_UTIL.print_hidden_if_readonly (
      p_item_name           => p_item.name,
      p_value               => p_value,
      p_is_readonly         => p_is_readonly,
      p_is_printer_friendly => p_is_printer_friendly );
    APEX_PLUGIN_UTIL.print_display_only (
      p_item_name        => p_item.name,
      p_display_value    => p_value,
      p_show_line_breaks => false,
      p_escape           => true,
      p_attributes       => p_item.element_attributes );
  ELSE
    l_name := APEX_PLUGIN.get_input_name_for_page_item(p_is_multi_value=>false);

    htp.p('<input type="text" name="'||l_name||'" id="'||p_item.name||'"
'||'value="'||htf.escape_sc(p_value)||'" size="'||p_item.element_width||'"
'||'maxlength="'||p_item.element_max_length||'" '||p_item.element_attributes||'
onKeyUp="fldRequired('''||p_item.name||''')"/>'),

    APEX_JAVASCRIPT.add_library (p_name=> 'requiredInColor',p_directory =>
p_plugin.file_prefix,p_version => null );

    APEX_JAVASCRIPT.add_onload_code (p_code => ' fldRequired('''||p_item.name||''')'),

  END IF;
  RETURN l_result;
END requiredInColor;

Replace the code in the PL/SQL section of the Required In Color plug-in and execute the page again. You can see that the Cost item is displayed with a white background for records that contain a Cost value. There is still much more you could do with this item. Adding real validation code to ensure that a value is entered and it is within specifications, for example, would be easy to do and you should be able to do that on your own.

Custom attributes are used to store metadata that can be added to any plug-in type. When adding a plug-in-based item to a page, you will be presented a prompt for each custom attribute attached to the type. You can assign up to ten custom attributes per plug-in, which allows for a great deal of flexibility. To keep things simple, we will assign a custom attribute to the Required In Color plug-in, which allows the developer to choose the color of the background of this item. We could add two attributes to control both the populated and unpopulated colors, but the mechanics are identical so we will stick with one in the interest of brevity.

The process of adding attributes is very simple. You navigate to the plug-in home page and edit the Required In Color plug-in. You'll notice that the Custom Attributes section reports that there are no attributes defined for this plug-in. Clicking the Add Attribute button displays the Edit Attribute page, as shown in Figure 12-12.

Figure 12.12. Edit Attribute page

Starting at the top of the Attribute definition, the Scope of the attribute refers to how the attribute can be used once the plug-in has been created. The Scope has two settings: Component and Application. If we set it to Application, then the developer using this plug-in would only be able to set the value of this attribute one time for the entire application. Using the Component settings allows for this attribute to be defined each time the plug-in is used.

The Attribute field is set to a numeric value that will be used to identify the attribute in code. The Display Sequence determines the order in which the Attributes are displayed in the APEX Builder and the Label is used to describe the attribute. We set the label to "Required Field Color."

The Settings section allows you to define the method the developer will use to set the value of the attribute. As you can see in Figure 12-13, there are several options from which to choose. For this example, we will use the Text type, as we want the developer to be able to enter a color value. We set the default value to #FEA5AD, so the text item's background will be rendered in color even if the developer forgets to set the value. You can see the definitions of the other settings by clicking on their labels.

Figure 12.13. Attribute type selection

The Conditions and Help Text settings are the same as with other APEX objects. For this example, we left them blank and clicked the Create button to finish the Attribute creation process. So now we have a custom attribute, but it doesn't change anything because our code doesn't know about it. You can set the value of this attribute by editing the item that is based on this plug-in, as shown in Figure 12-14.

Figure 12.14. Item edit page

Your plug-in's custom attribute (or attributes) now show up in their own section on the item edit page called "Settings." For plug-ins with no custom attributes, the Settings section will not be displayed. You can see the default value that was set when the custom attribute was created, but you can change it to any value you like (just make sure it is a valid HTML color). To include our new attribute in the action, we have to make some code changes. First, we need to change the plug-in's PL/SQL code so that it has access to the attribute's value. Then we will modify the requiredInColor.js JavaScript file to use the new attribute value to paint the background of the item. Listing 12-6 shows the changes we made to the PL/SQL code. A new variable, l_background, is used to store the value of the single, custom attribute we added to the plug-in. We used the following declaration to gain access to the attribute's value:

l_background apex_application_page_items.attribute_01%type := p_item.attribute_01

When the l_background variable was defined, we had to know that the attribute used to store the background color was attribute number 1 because we can't refer to it by name. This was easy in our example since we only have one, but if you had multiple custom attributes on the plug-in, you would have to be sure about which ones you were using.

We also had to change the calls to htp.p and the APEX_JAVASCRIPT.add_onload_code to include the l_background parameter in when the fldRequired JavaScript function is called.

function requiredInColor (
  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_name varchar2(30);
  l_result      apex_plugin.t_page_item_render_result;
  l_background  apex_application_page_items.attribute_01%type := p_item.attribute_01;
BEGIN
  IF p_is_readonly OR p_is_printer_friendly THEN
    APEX_PLUGIN_UTIL.print_hidden_if_readonly (
      p_item_name           => p_item.name,
      p_value               => p_value,
      p_is_readonly         => p_is_readonly,
      p_is_printer_friendly => p_is_printer_friendly );
    APEX_PLUGIN_UTIL.print_display_only (

p_item_name        => p_item.name,
      p_display_value    => p_value,
      p_show_line_breaks => false,
      p_escape           => true,
      p_attributes       => p_item.element_attributes );
  ELSE
    l_name := APEX_PLUGIN.get_input_name_for_page_item(p_is_multi_value=>false);

    htp.p('<input type="text" name="'||l_name||'" id="'||p_item.name||'"
'||'value="'||htf.escape_sc(p_value)||'" size="'||p_item.element_width||'"
'||'maxlength="'||p_item.element_max_length||'" '||p_item.element_attributes||'
onKeyUp="fldRequired('''||p_item.name||''','''||l_background||''')"/>'),

    APEX_JAVASCRIPT.add_library (p_name=> 'requiredInColor',p_directory =>
p_plugin.file_prefix,p_version => null );

        APEX_JAVASCRIPT.add_onload_code (p_code => '
fldRequired("'||p_item.name||'","'||l_background||'")')

  END IF;

  RETURN l_result;

END requiredInColor;

To round out the changes related to our custom attribute, we need to modify the requiredInColor.js file, as it needs to receive two parameters instead of one. All we need to do is add a parameter, bkgColor, in the declaration of the fldRequired function and then use that variable name to color the item's background when it's empty. The new code is shown in Listing 12-7.

function fldRequired(fldName,bkgColor)
{
  vValue = document.getElementById(fldName).value;
  if (!vValue)
  {
    document.getElementById(fldName).style.background=bkgColor;
  }
  else
  {
    document.getElementById(fldName).style.background="#FFFFFF";
  }
}

We're not done just yet, however. Remember that we have to upload the requiredInColor.js file so the plug-in has access to our changes. If a file with this name is already associated with the plug-in (which it is), we must first delete it as APEX 4.0 does not allow you implicitly replace an uploaded file. Using the edit plug-in page as shown in Figure 12-15, you must edit the existing requiredInColor file so you can delete it; then upload it again so our new changes are available.

Figure 12.15. Item edit page

Once you apply the changes to the plug-in, you can execute your form. It should look just like it did before because the default value of the plug-in's attribute is the same. Try modifying the value of the "Required Field Color" setting on the P28_COST_REQUIRED item to some other color. Figure 12-16 shows our attribute being changed to yellow.

Figure 12.16. Custom Attribute setting changed

When you execute the page now, as shown in Figure 12-17, the Cost item's background is yellow when the value is null. You may have to back out the existing value to see the color change. Since we're talking in black and white, you'll have to take our word for it.

Figure 12.17. Custom Attribute setting changed

The functionality we created with this plug-in was pretty simple, but it took quite a bit of work to get it done. Now that it's done, though, it can be used everywhere and made available to fellow APEX developers worldwide.