/******************************************/
/**** RENDER FUNCTION ****/
/******************************************/
-- This is the procedure which renders the HTML constituting our page item.
FUNCTION render_changeCase (
p_item in apex_plugin.t_page_item, --contains details such as the name and label of the item as well as the values of all the custom attributes
p_plugin in apex_plugin.t_plugin, -- contains details such as the name of the plugin ("uk.co.tulley.changecase" in this case)
p_value in varchar2, -- contains the value of the item itself (e.g. what the user has typed into the text field)
p_is_readonly in boolean, -- indicates whether the item should be rendered as Read Only
p_is_printer_friendly in boolean) -- indicates whether item should be rendered so as to be "Printer Friendly"
return apex_plugin.t_page_item_render_result
IS
-- l_do_what: Value will either be UPPER or LOWER depending on what the user has chosen from custom attribute 1
-- for this instance of the plugin-based item. For this plugin, Custom Attribute 1 is referred to as "Case Alteration Option"
-- and defaults to Uppercase when creating a new plugin item of this type.
l_do_what apex_application_page_items.attribute_01%type := p_item.attribute_01;
-- l_name: The value to place in the name= attribute of the tag for this item. This value is generated by Apex
-- and we retrieve this value below with a call to apex_plugin.get_input_name_for_page_item
l_name varchar2(30);
-- l_result: Apex mandates that the PLSQL render function for a plugin returns apex_plugin.t_page_item_render_result.
-- For reference, this is defined in the WWV_FLOW_PLUGIN package as
--
-- type t_page_item_render_result is record (
-- is_navigable boolean default false,
-- navigable_dom_id varchar2(255) /* should only be set if navigable element is not equal to item name */
-- );
l_result apex_plugin.t_page_item_render_result;
BEGIN
-- If the item is to be displayed as Read Only or in Printer Friendly mode then we don't
-- want to output an tag as we normally would but rather a hidden field and a
-- tag.
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
-- If the item is to be displayed normally then we output an tag with an onchange
-- javascript event so that the text in the input is uppercased or lowercased as appropriate
-- (depending on whether the developer chose Uppercase or Lowercase from the Custom Attribute 1
-- ("Case Alteration Option") for this instance of this plugin item.
-- See note for l_name in the declaration block at the top of this code for details of what this
-- line is doing.
l_name := APEX_PLUGIN.get_input_name_for_page_item(p_is_multi_value=>false);
-- Output the HTML to render the Text Field.
HTP.p( '');
-- changecase.js was added to the Plugin's "Files" when this plugin was created. changecase.js contains
-- just one Javascript function called changeCase(). The call below to APEX_JAVASCRIPT.add_library ensures
-- that Apex includes a reference to changecase.js in the source of the page whenever a page contains
-- an instance of this Plugin Item. APEX_JAVASCRIPT.add_library is clever in that it will only ever include
-- one reference to the Javascript file in the source of the page even if there are multiple instances of
-- this Plugin Item on a single page.
APEX_JAVASCRIPT.add_library (
p_name => 'changecase', -- The name of the file (without the .js extension)
p_directory => p_plugin.file_prefix, -- Where Apex should look for this file. In this case, Plugin's "Files" area in the DB.
p_version => null );
END IF;
RETURN l_result;
END render_changecase;
/******************************************/
/**** VALIDATION FUNCTION ****/
/******************************************/
-- The validation function for the ChangeCase plugin. As we saw in the render_changecase function above, the
-- tag will be created with an onchange event so that on the client-side the contents of the field
-- are either uppercased or lowercased automatically as appropriate. However, even with this client-side code
-- in place it is still possible that the field will be submitted with uppercase letters when it should have
-- only lowercase or vice versa (as a result, perhaps, of tampering by the user using a tool such as Firefox
-- Tamper Data [https://addons.mozilla.org/en-US/firefox/addon/966/]).
-- For this reason, therefore, we perform Server Side validation of the submitted value. This validation is
-- fired by Apex before any other validations which may have been created on the current Apex page.
FUNCTION validate_changecase (
p_item IN APEX_PLUGIN.t_page_item, -- contains details such as the name and label of the item as well as the values of all the custom attributes
p_plugin IN APEX_PLUGIN.t_plugin, -- contains details such as the name of the plugin ("uk.co.tulley.changecase" in this case)
p_value IN VARCHAR2) -- contains the value of the item itself (e.g. what the user has typed into the text field)
RETURN APEX_PLUGIN.t_page_item_validation_result
IS
-- Value will either be UPPER or LOWER depending on what the user has chosen from custom attribute 1
-- for this instance of the plugin-based item.
l_do_what apex_application_page_items.attribute_01%type := p_item.attribute_01;
-- l_result: Apex mandates that the return type of a plugin validation function is
-- For reference, this type is defined in the APEX_PLUGIN package as:
--
-- type t_page_item_validation_result is record (
-- message varchar2(32767),
-- display_location varchar2(40), /* if not set the application default will be used */
-- page_item_name varchar2(255) ); /* if not set the validated page item name will be used */
l_result APEX_PLUGIN.t_page_item_validation_result;
BEGIN
-- If the field is supposed to contain only uppercase letters and has been submitted with lowercase letters
-- then fail the validation and return a message indicating such.
IF l_do_what = 'UPPER' AND regexp_instr(p_value,'[a-z]') > 0 THEN
l_result.message := 'All letters in the field "'||p_item.label||'" must be uppercase.';
-- Similarly, fail the validation and return an error message if the field is suppoed to contain only
-- lowercase letters but has been submitted with uppercase letters.
ELSIF l_do_what = 'LOWER' AND regexp_instr(p_value,'[A-Z]') > 0 THEN
l_result.message := 'All letters in the field "'||p_item.label||'" must be lowercase.';
END IF;
-- Specify that we want the validation message to be displayed only inline in the notification area
-- (usually at the top of the Apex page). Other possible values are:
-- APEX_PLUGIN.c_inline_with_field
-- APEX_PLUGIN.c_inline_with_field_and_notif
-- APEX_PLUGIN.c_on_error_page
l_result.display_location := APEX_PLUGIN.c_inline_in_notifiction;
-- If l_reuslt.message is NULL then the validation has deemed to have passed.
-- If it is not NULL then the validation is deemed to have failed and the contents of l_result.message will
-- be displayed on the Apex page telling the user why the validation has failed.
RETURN l_result;
END validate_changecase;