Creating plugin item types using APEX 4.0

With the long awaited early adopter release of Application Express 4.0, we finally can create custom item types. This is something I’ve been waiting for a long time. And with APEX now using the jQuery and jQuery-UI libraries by default I decided to have a go on finding out how easy it actually is to create an item type based on the jQuery-UI slider widget. After reading and exploring some of Patrick Wolf’s documentation, it was pretty easy to find out how to go about.

The first thing we have to do is to create the custom item type itself and adding some attributes to it. These attributes will show up when a new application control is created.

• First create the plugin by navigating to: Shared components > User interface > Plugins -> Create
• Give the plugin a name: “slider”
• Set the type of plugin to: Item
• Set the internal name to something like “com.test.apex.slider”
  This name must be unique, so it’s agood thing to reverse your company’s domain before the plugin’s name to create a proper namespace.

For our slider we want a few attributes: minimum value, maximum value, number of steps and the width of the slider itself.
Navigate to the “Attributes region” and add the attributes as follows:

APEX 4.0 custom item type attributes

Once the attributes are created, we need to create a process that renders the html for our item type.
The jQuery-UI slider widget uses a DIV for the slider itself to project on, so we need to output that, along with a normal readonly textitem to show and submit the slidervalue back to APEX:

procedure render_slider (
  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 )
is
  l_escaped_value varchar2(32767) := sys.htf.escape_sc(p_value);
  l_name          varchar2(30)    := apex_plugin.get_input_name_for_page_item(false);
  --
  -- get the values of the custom item type attributes
  --
  l_min           apex_application_page_items.attribute_01%type := p_item.attribute_01;
  l_max           apex_application_page_items.attribute_02%type := p_item.attribute_02;
  l_steps         apex_application_page_items.attribute_03%type := p_item.attribute_03;
  l_slider_width  apex_application_page_items.attribute_04%type := p_item.attribute_04;
begin
  --
  -- Show if debug = "YES", ability to debug turned OFF by default in APEX 4.0
  --
  if wwv_flow.g_debug then
    apex_plugin.debug_page_item (
      p_plugin              => p_plugin
    , p_page_item           => p_item
    );
  end if;

  --
  -- Render the slider div with prefixed id so output will be SLIDER_{ITEM_NAME}
  -- along with a text input {ITEM_NAME} which will hold the actual value of the slider
  --
  htp.p('<table><tr><td><div style="width:' || l_slider_width || 'px;"' ||
                  ' id="SLIDER_' || p_item.name || '"></div></td><td>'  ||
                  '<input type="text" readonly="readonly" '             ||
                  'name="'      || l_name                    ||'" ' ||
                  'id="'        || p_item.name               ||'" ' ||
                  'value="'     || l_escaped_value           ||'" ' ||
                  'maxlength="' || p_item.element_max_length ||'" ' ||
                  'size="'      || p_item.element_width      ||'" ' ||
                  p_item.element_attributes ||' /></td></tr></table>');

  --
  -- Register the conversion from div to slider to execute when the page is loaded
  -- using our newly created attribute values
  --
  apex_javascript.add_onload_code (
            p_code => 'apex.jQuery("#SLIDER_'||p_item.name||'").slider({'
                   || '  min: '   || l_min
                   || ', max: '   || l_max
                   || ', value: ' || nvl(p_value,'0')
                   || ', step: '  || l_steps
                   || ', slide: function(event,ui) {
                          apex.jQuery("#' || p_item.name || '").val(ui.value);
                         }'
                   || '});'
   );
end;

• Paste the code to render the custom item into the “Source” region.

One more thing we have to do before creating the actual slider item on a page:

• In the “Callbacks” region enter “render_slider” (or call to your package procedure) in the “Render procedure name”.
• Hit “Create” or “Apply changes”

To add a Slider, create a new page in your application and create a new “Page control”. Choose item -> Plugin and there you will see your newly created “slider” item type listed.

• Give your item a name like you normally would e.g. P1_AMOUNT, and attach it to a region.
• Supply your item with a label and give the item a width (this is actually the size of the input type showing the slider’s value)

When you hit “Next” you will see the list of attributes you created with your custom item type definition.

APEX 4 Create Item Dialog

• Give the attributes some values and hit “Next”
• Optionally supply a source- and default value and create the item.

Now when you run the page, you should be seeing you slider.

Slider demo

Ofcourse you should always create a validation process and attach it to your item type to be sure no malicious values can be submitted, and you might want to replace the readonly input field with a regular one, so you can type in the value and sync with it.

I’m very surprised on how fast you can create your own item types, something I’ve been waiting for a long time. We’ve been using jQuery extensively on our projects and it’s great we finally can create and access custom attributes in a well-structured manner. Before that we had to “abuse” some default item attributes to supply values for let’s say the width of the slider, or create multiple versions of the jQuery-UI widgets on a page with their options hardcoded in them.

This feature truly adds unlimited possibilities to create custom interfaces, and even better: I think we’re going to see a lot of plugins available from the community any time soon !

Ratings:

VN:F [1.9.22_1171]

please wait...

Rating: 4.5/5 (6 votes cast)

Tags: Apex, APEX4, Application Express, Custom item types, Oracle

• 

 Print This PDF Version