18 APEX_PLUGIN

The APEX_PLUGIN package provides the interface declarations and some utility functions to work with plug-ins.

Topics:

Data Types

The data types used by the APEX_PLUGIN package are described in this section.

Data Types:

c_*

The following constants are used for display_location in the page item validation function result type t_page_item_validation_result.

c_inline_with_field           constant varchar2(40) := 'INLINE_WITH_FIELD';
c_inline_with_field_and_notif constant varchar2(40) := 'INLINE_WITH_FIELD_AND_NOTIFICATION';
c_inline_in_notification      constant varchar2(40) := 'INLINE_IN_NOTIFICATION';
c_on_error_page               constant varchar2(40) := 'ON_ERROR_PAGE';

t_authentication

  type t_authentication is record (
    id                   number,
    name                 varchar2(255),
    invalid_session_url  varchar2(4000),
    logout_url           varchar2(4000),
    plsql_code           clob,
    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),
    attribute_11         varchar2(32767),
    attribute_12         varchar2(32767),
    attribute_13         varchar2(32767),
    attribute_14         varchar2(32767),
    attribute_15         varchar2(32767),
    --
    session_id           number,
    username             varchar2(255) );

t_authentication_ajax_result

  type t_authentication_ajax_result is record (
    dummy                boolean );

t_authentication_auth_result

  type t_authentication_auth_result is record (
    is_authenticated     boolean,
    redirect_url         varchar2(4000),
    log_code             number,
    log_text             varchar2(4000),
    display_text         varchar2(4000) );

t_authentication_inval_result

  type t_authentication_inval_result is record (
    redirect_url         varchar2(4000) );

t_authentication_logout_result

  type t_authentication_logout_result is record (
    redirect_url         varchar2(4000) );

t_authentication_sentry_result

  type t_authentication_sentry_result is record (
    is_valid             boolean );

t_dynamic_action

The following type is passed into all dynamic action plug-in functions and contains information about the current dynamic action.

type t_dynamic_action is record (
    id           number,
    action       varchar2(50),
    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) );

t_dynamic_action_ajax_result

The following type is used as the result type for the AJAX function of a dynamic action type plug-in.

type t_dynamic_action_ajax_result is record (
    dummy boolean /* not used yet */
    );

t_dynamic_action_render_result

The following type is used as the result type for the rendering function of a dynamic action plug-in.

type t_dynamic_action_render_result is record (
    javascript_function varchar2(32767),
    ajax_identifier     varchar2(255),
    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) );

t_page_item

The following type is passed into all item type plug-in functions and contains information about the current page item.

type t_page_item is record (
    id                          number,
    name                        varchar2(255),
    label                       varchar2(4000),
    plain_label                 varchar2(4000),
    placeholder                 varchar2(255),
    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_css_classes         varchar2(255),
    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) );

t_page_item_ajax_result

The following type is used as the result type for the AJAX function of an item type plug-in.

type t_page_item_ajax_result is record (
    dummy boolean /* not used yet */
    );

t_page_item_render_result

The following type is used as the result type for the rendering function of an item type plug-in.

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 */
    );

t_page_item_validation_result

The following type is used as the result type for the validation function of an item type plug-in.

type t_page_item_validation_result is record (
    message          varchar2(32767),
    display_location varchar2(40),    /* if not set the application default is used */
    page_item_name   varchar2(255) ); /* if not set the validated page item name is used */

t_plugin

The following type is passed into all plug-in functions and contains information about the current plug-in.

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) );

t_process

The following type is passed into all process type plug-in functions and contains information about the current process.

type t_process is record (
    id                   number,
    name                 varchar2(255),
    success_message      varchar2(32767),
    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) );

t_process_exec_result

The following type is used as the result type for the execution function of a process type plug-in.

type t_process_exec_result is record (
    success_message varchar2(32767)
    );

t_region

The following type is passed into all region type plug-in functions and contains information about the current region.

type t_region is record (
    id                   number,
    static_id            varchar2(255),
    name                 varchar2(255),
    type                 varchar2(255),
    source               varchar2(32767),
    ajax_items_to_submit varchar2(32767),
    fetched_rows         pls_integer,
    escape_output        boolean,
    no_data_found_message varchar2(32767),
    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),
    attribute_11         varchar2(32767),
    attribute_12         varchar2(32767),
    attribute_13         varchar2(32767),
    attribute_14         varchar2(32767),
    attribute_15         varchar2(32767),
    attribute_16         varchar2(32767),
    attribute_17         varchar2(32767),
    attribute_18         varchar2(32767),
    attribute_19         varchar2(32767),
    attribute_20         varchar2(32767),
    attribute_21         varchar2(32767),
    attribute_22         varchar2(32767),
    attribute_23         varchar2(32767),
    attribute_24         varchar2(32767),
    attribute_25         varchar2(32767));

t_region_ajax_result

The following type is used as result type for the AJAX function of a region type plug-in.

type t_region_ajax_result is record (
    dummy boolean /* not used yet */
    );

t_region_render_result

The following type is used as the result type for the rendering function of a region type plug-in.

type t_region_render_result is record (
    dummy boolean /* not used yet */
    );

GET_AJAX_IDENTIFIER Function

This function returns the AJAX identifier used to call the AJAX callback function defined for the plug-in.

Note:

This function only works in the context of a plug-in rendering function call and only if the plug-in has defined an AJAX function callback in the plug-in definition.

Syntax

APEX_PLUGIN.GET_AJAX_IDENTIFIER
RETURN VARCHAR2;

Parameters

None.

Example

This is an example of a dynamic action plug-in rendering function that supports an AJAX callback.

function render_set_value (
    p_dynamic_action in apex_plugin.t_dynamic_action )
    return apex_plugin.t_dynamic_action_render_result
is
    l_result                apex_plugin.t_dynamic_action_render_result; 
begin
    l_result.javascript_function := 'com_oracle_apex_set_value';
    l_result.ajax_identifier     := wwv_flow_plugin.get_ajax_identifier;
    return l_result;
end;

GET_INPUT_NAME_FOR_PAGE_ITEM Function

Use this function when you want to render an HTML input element in the rendering function of an item type plug-in.For the HTML input element, for example, <input type="text" id="P1_TEST" name="xxx">, you have to provide a value for the name attribute so that Oracle Application Express can map the submitted value to the actual page item in session state. This function returns the mapping name for your page item. If the HTML input element has multiple values, such as a select list with multiple="multiple", then set p_is_multi_value to true.

Note:

This function is only useful when called in the rendering function of an item type plug-in.

Syntax

APEX_PLUGIN.GET_INPUT_NAME_FOR_PAGE_ITEM (
    p_is_multi_value  IN BOOLEAN)
RETURN VARCHAR2;

Parameters

Table 18-1 describes the parameters available in the GET_INPUT_NAME_FOR_PAGE_ITEM function.

Table 18-1 GET_INPUT_NAME_FOR_PAGE_ITEM Parameters

Parameter Description

p_is_multi_value

Set to TRUE if the HTML input element has multiple values. If not, set to FALSE. HTML input elements with multiple values can be checkboxes and multi select lists.


Example

The following example outputs the necessary HTML code to render a text field where the value gets stored in session state when the page is submitted.

sys.htp.prn (
    '<input type="text" id="'||p_item.name||'" '||
    'name="'" '||
    'value="'||sys.htf.escape_sc(p_value)||'" '||
    'size="'||p_item.element_width||'" '||
    'maxlength="'||p_item.element_max_length||'" '||
    coalesce(p_item.element_attributes, 'class="text_field"')||' />' );