Follow Us on Twitter

Creating plugin item types using APEX 4.0

by Maarten van Luijtelaar on December 21, 2009 · 11 comments

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

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.

apex4_cit_attr2

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.

apex4_cit_result

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 !

Creating plugin item types using APEX 4.0, 4.5 out of 5 based on 6 ratings
Ratings:
VN:F [1.9.22_1171]
Rating: 4.5/5 (6 votes cast)

11 comments on “Creating plugin item types using APEX 4.0

  1. Pingback: Tweets die vermelden Creating plugin item types using Apex 4.0 -- Topsy.com

  2. Hi, in the latest version of apex, the Callbacks, only accept a function, you can’t specify a procedure.
    When i use procedure name “render_slider” in the section of “callbacks” definition, the application accept the entry, but when i execute the page, the application return me
    the following error:
    ORA-06550: line 50, column 46: PLS-00201: identifier ‘DAILYINC.RENDER_SLIDER’ must be declared ORA-06550: line 50, column 1: PL/SQL: Statement ignored

    any suggest?
    Best Regards

    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  3. Maarten van Luijtelaar on said:

    Hi Paolo,

    You are right, the implementation of the callback functions changed a little in the production release of APEX 4.0. Instead of creating a procedure that renders the html for an item plugin, a function should be created returning the apex_plugin.t_page_item_render_result PLSQL-type.

    I created a package “pkg_apex_plugin” containing the “render_slider” function so it can be called from “Callbacks”->”Render function Name” without having to declare the function in the “Source” region.
    One more thing you shouldn’t forget: In your page template include the jQuery UI script and the css necessary to render the slider nicely by adding the lines

    <link href="#IMAGE_PREFIX#libraries/jquery-ui/1.8/themes/base/jquery.ui.slider.css" rel="stylesheet" type="text/css" />
    <script src="#IMAGE_PREFIX#libraries/jquery-ui/1.8/ui/minified/jquery.ui.slider.min.js" type="text/javascript"></script>

    just after the #HEAD# substitution variable.
    You can download the package containing the slider render code here.

    VN:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  4. Maarten van Luijtelaar on said:

    Hi Paolo,

    Glad it worked for you.
    Be sure to keep track of upcoming Whitebooks since one of them will cover the ins and outs of APEX 4.0 plugins.

    Regards,

    Maarten

    VN:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  5. Thank you so much, this was very helpful.

    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
  6. Avindra Goolcharan on said:

    Still no luck with the 4.0 files in 4.2. Getting the following error:

    ORA-06550: line 10, column 1: PLS-00103: Encountered the symbol “CREATE” when expecting one of the following: begin function pragma procedure subtype type current cursor delete exists prior

    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
    • Hello Avindra,

      Can you elaborate a bit more about the steps you are taking and what you are trying to accomplish?
      I’m struggling a bit to relate your problem to this article.

      VN:F [1.9.22_1171]
      Rating: 0 (from 0 votes)
      • Avindra Goolcharan on said:

        Hi Michel,

        I was running into that error when I tried creating a new plugin per the instructions in Maarten’s comment.

        I was able to resolve my issue by downloading a random Apex 4.2 compatible plugin and using it as a template instead.

        VA:F [1.9.22_1171]
        Rating: 0 (from 0 votes)
  7. kala on said:

    I have followed through the instructions, created a plug-in but getting
    ORA-06550: line 4, column 50: PLS-00201: identifier ‘RENDER_SLIDER’ must be declared ORA-06550: line 4, column 1: PL/SQL: Statement ignored.

    I am not sure how do i call render_slider function when i create the plug-in item
    and how define callback function??

    Can you please help

    VA:F [1.9.22_1171]
    Rating: 0 (from 0 votes)
    • Hello Kala,

      I think you ran into the same problem as Paolo did. Please have a look at the solution Maarten provided in his comment of August 20, 2010 at 11:30 pm.

      VN:F [1.9.22_1171]
      Rating: 0 (from 0 votes)

Leave a Reply

Your email address will not be published. Required fields are marked *

*

* Copy This Password *

* Type Or Paste Password Here *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

 

Previous post:

Next post:

About Whitehorses
Company profile
Services
Technology

Whitehorses website

Home page
Whitebooks
Jobs

Follow us
Blog post RSS
Comment RSS
Twitter