Overview | Package | Object Type | Deprecated | Index | Help
| Oracle Application Server Portal PL/SQL API Reference - 10.1.4
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES
SUMMARY: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE | DETAIL: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE

## Package wwa_app_module

This package contains methods for working with Oracle Portal form components.

An Oracle Portal form component displays a customized form that can be used as an interface for updating tables, executing stored procedures, and generating other customized forms. The APIs described here can be used for all three types of form components you can build with Oracle Portal:

- A form based on a table or view enables end users to insert, update, and delete data in a database table or view.
- A master-detail form displays a master row and multiple detail rows within a single HTML page. The form contains fields for updating values in two database tables or views.
- A form based on a procedure enables end users to insert, update, and delete data in a database stored procedure.

Scope:
  Public
Since:
  Oracle Portal 3.0.9

Exception Summary
`DATA_INTEGRITY_VIOLATED` A user defined exception to handle data integrity violation.

Variable Summary
`empty_vc_arr` Empty PL/SQL table of type wwv_utl_api_types. | `wwv_utl_api_types.vc_arr`

Function/Procedure Summary
`about` Displays metadata associated with a form component. | ``
`accept` Accepts a flexible number of name-value pairs from a form component. | ``
`accept_customize` Accepts a flexible number of name-value pairs from a customization screen for a form component. | ``
`customize` Display the customization screen for a form component. | ``
`deregister_portlet` Not currently used. | ``
`describe_portlet_parameters` Returns a table of portlet parameters for a form component. | `wwpro_api_provider.portlet_parameter_table`
`file_download` Displays a form component item of type 'File Upload (Binary)/ File Upload (Intermedia)'. | ``
`get_comp_event_items` Not currently used. | `wwa_api_lovvalues`
`get_comp_items` Not currently used. | `wwa_api_lovvalues`
`get_target` Gets the target URL and target mode of a form component. | ``
`help` Displays help text associated with a form component. | ``
`is_portlet_runnable` Checks if a portlet can be contacted. | `boolean`
`link` Starts a form component session via a link. | ``
`new_instance` Creates a new session for a form component. | ``
`register_portlet` Not currently used. | ``
`set_target` Sets the target URL for a form component. | ``
`show` Displays a form component. | ``
`show_portlet` Displays a form component as a portlet on a page. | ``

Exception Detail

### DATA_INTEGRITY_VIOLATED

    DATA_INTEGRITY_VIOLATED exception

  A user defined exception to handle data integrity violation.

  This exception is raised for User A when:

  - User A queries a record.
  - User B queries the same record and updates/deletes it.
  - User A tries to update/delete a record previously queried.

  Since:
    Oracle Portal 9.0.2

Variable Detail

### empty_vc_arr

    empty_vc_arr wwv_utl_api_types.vc_arr

  Empty PL/SQL table of type wwv_utl_api_types.vc_arr

  This variable is used to provide a default value of an empty PL/SQL table to parameters/other variables of type wwv_utl_api_types.vc_arr

  Since:
    Oracle Portal 3.0.9
  See Also:
    wwv_utl_api_types.vc_arr

Function/Procedure Detail

### about

    procedure about(
        p_module_id in number
    )

  Displays metadata associated with a form component. This metadata includes inputs given by the user while building the form component.

  Example:

        portal_schema.wwa_app_module.about
        (
             p_module_id => 1080540748
        );

  Parameters:
    `p_module_id` - the module ID of the form component
  Since:
    Oracle Portal 3.0.9

### accept

    procedure accept(
        num_entries in number default null,
        name_array in wwv_utl_api_types.vc_arr default empty_vc_arr,
        value_array in wwv_utl_api_types.vc_arr default empty_vc_arr,
        reserved in wwv_utl_api_types.vc_arr default empty_vc_arr
    )

  Accepts a flexible number of name-value pairs from a form component. This procedure gets invoked when the form is submitted.

  The user inputs to the form and the corresponding field names are passed to the procedure as PL/SQL tables.

  Example:

  Consider a HTML form whose :

      ACTION="http://host-name:port/pls/dad/!portal-schema.wwa_app_module.
       accept"  METHOD = "POST"

  The user can submit any number of HTML form elements and their values while having different names for the form elements.

  The HTML form element names are passed, as a PL/SQL table, to name_array.

  The HTML form element values are passed, as a PL/SQL table, to value_array.

  Parameters:
    `num_entries` - not used (as per mod_pl/sql documentation)
    `name_array` - PL/SQL table containing the names of all the HTML form elements that get submitted when the HTML form is submitted
    `value_array` - PL/SQL table containing the values of all the HTML form elements that get submitted when the HTML form is submitted
    `reserved` - not used (as per mod_pl/sql documentation)
  Since:
    Oracle Portal 3.0.9

### accept_customize

    procedure accept_customize(
        num_entries in number default null,
        name_array in wwv_utl_api_types.vc_arr default empty_vc_arr,
        value_array in wwv_utl_api_types.vc_arr default empty_vc_arr,
        reserved in wwv_utl_api_types.vc_arr default empty_vc_arr,
        p_mode in integer default wwpro_api_provider . mode_show_edit
    )

  Accepts a flexible number of name-value pairs from a customization screen for a form component. This procedure gets invoked when the form is submitted.

  The user inputs to the customization screen and the corresponding field names are passed to the procedure as PL/SQL tables.

  Example:

  Similar to wwa_app_module.accept procedure. See above.

  Parameters:
    `num_entries` - not used (as per mod_pl/sql documentation)
    `name_array` - PL/SQL table containing the names of all the HTML form elements submitted when the HTML form is submitted
    `value_array` - PL/SQL table containing the values of all the HTML form elements submitted when the HTML form is submitted
    `reserved` - not used (as per mod_pl/sql documentation)
    `p_mode` - Customize Mode (Edit, Edit Defaults)
  Since:
    Oracle Portal 3.0.9

### customize

    procedure customize(
        p_module_id in integer,
        p_back_page_url in varchar2 default null,
        p_page_url in varchar2 default null,
        p_exec_mode in varchar2 default wwv_global . run_as_normal,
        p_reference_path in varchar2 default null,
        p_provider_id in integer default null,
        p_mode in integer default wwpro_api_provider . mode_show_edit
    )

  Display the customization screen for a form component.

  Example:
  Consider the procedure helloworld in the PORTAL_SCHEMA that prints "Hello World". To display this message when you click the Cancel button or OK button, call the customize procedure as follows:

         wwa_app_module.customize
         (
             p_module_id     => 1080540748,
             p_back_page_url => 'portal_schema.helloworld'
         );

  Note: You need to grant the execute privilege to the helloworld procedure to portal_schema_public database user.

  Parameters:
    `p_module_id` - the module ID of the form component
    `p_back_page_url` - the URL (encoded) to display when clicking the OK or Cancel button
    `p_page_url` - not currently used
    `p_exec_mode` - Indicates the display mode:
    - Full page mode (wwv_global.RUN_AS_NORMAL)
    - Portlet mode (wwv_global.RUN_AS_PORTLET)
    `p_reference_path` - the reference path of the portlet (in portlet mode only)
    `p_provider_id` - the ID of the provider to which the form component belongs.
    `p_mode` - Customize Mode (Edit, Edit Defaults)
  Since:
    Oracle Portal 3.0.9

### deregister_portlet

    procedure deregister_portlet(
        p_portlet_instance in wwpro_api_provider.portlet_instance_record
    )

  Not currently used.

  Parameters:
    `p_portlet_instance` - record of type wwpro_api_provider.portlet_instance_record
  Since:
    Oracle Portal 3.0.9

### describe_portlet_parameters

    function describe_portlet_parameters(
        p_provider_id in integer,
        p_portlet_id in integer,
        p_language in varchar2
    ) return wwpro_api_provider.portlet_parameter_table

  Returns a table of portlet parameters for a form component.

  Example:

         declare
             l_params wwpro_api_provider.portlet_parameter_table;
         begin
             l_params := portal_schema.describe_portlet_parameters
         (
             p_provider_id   => 849478,
             p_portlet_id    => 1100897857,
             p_language      => portal_schema.wwctx_api.get_nls_language
         );
       end;

  Parameters:
    `p_provider_id` - the ID of the provider through which the form component is accessed as a portlet
    `p_portlet_id` - the module ID of the form component
    `p_language` - the language setting of the Portal. This can be accessed via .wwctx_api.get_nls_language
  Returns:
    a table of public portlet parameters. For example, for a form component based on SCOTT.EMP table returns the following:
    - _show_header
    - _rowid
    - EMPNO
    - ENAME
    - JOB, etc.
    Except for _show_header and _rowid, the rest are the columns of the table on which the form component is based. These parameters can be used as described in the wwa_app_module.link examples.
  Since:
    Oracle Portal 3.0.9

### file_download

    procedure file_download(
        p_id in integer,
        p_block in varchar2,
        p_object in varchar2,
        p_source in varchar2
    )

  Displays a form component item of type 'File Upload (Binary)/ File Upload (Intermedia)'.

  If a form component is based on a table with column(s) such as BLOB/ ORDSYS.ORDIMAGE/ ORDSYS.ORDAUDIO/ORDSYS.ORDVIDEO, by default, the corresponding item types are File Upload (Binary) /File Upload (Intermedia). There would be procedures such as upload_x and download_x in the generated package (where x=1,2,3,4,5...depending on the number of BLOB/Intermedia columns) that uploads and downloads the Intermedia/BLOB content.

  When a query operation is performed, the results display a download link (or an image if the mime type has been set to an image type). This procedure is invoked when you click the download link, which in turn invokes one of the download_x procedures to perform the actual download.

  Example:
  Example applicable for Oracle9iAS Portal 9.0.2 or later. Consider a form component based on a table named table_of_songs (id number, audio ORDSYS.ORDAUDIO). This form component has an item named 'AUDIO' which when run, uploads a .wav or .mp3 file. To generate hyperlinks that download these files (after a query), the following code is required in the 'Additional PL/SQL' section called 'after displaying the page':

        declare
            l_block varchar2(200) := 'DEFAULT';
            l_OBJECT varchar2(200) := 'AUDIO';
            l_rowid varchar2(200);
            l_session_id integer;
            l_state varchar2(200);
        begin
            l_state := p_session.get_value_as_varchar2(
                p_block_name     => l_block,
                p_attribute_name => '_FORM_STATE'
              );
            if l_state = 'UPDATE_AND_DELETE' then
               l_session_id := p_session.get_id;
               l_rowid := p_session.get_value_as_varchar2(
                  p_block_name       => l_block,
                  p_attribute_name   => '_ROWID'
               );
             htp.anchor(curl=>'http://host:port/pls/dad/portal_schema.'||
                  'wwa_app_module.file_download?p_id='||l_session_id||
                   '&p_block='||l_block||
                  '&p_object='||l_object||
                  '&p_source='||portal_schema.wwv_htf.url_encode(l_rowid),
                  ctext => 'my link');
            end if;
        end;

  Note: For this code example to work it must be written in the 'Additional PL/SQL' section named 'after displaying the page'.

  Parameters:
    `p_id` - the session ID. This parameter is available in Oracle9iAS Portal 9.0.2 or later.
    `p_block` - the form block to which the form element of type File Upload (Binary)/File Upload (Intermedia) belongs.
    `p_object` - the form element name of type File Upload (Binary)/ File Upload (Intermedia)
    `p_source` - the ROWID of the row from which the BLOB/INTERMEDIA column is to be fetched
  Since:
    Oracle Portal 3.0.9

### get_comp_event_items

    function get_comp_event_items(
        p_provider_id in integer,
        p_portlet_id in integer
    ) return wwa_api_lovvalues

  Not currently used.

  Parameters:
    `p_provider_id` - the provider ID
    `p_portlet_id` - the portlet ID
  Returns:
    object of type wwa_api_lovvalues
  Since:
    Oracle Portal 3.0.9

### get_comp_items

    function get_comp_items(
        p_provider_id in integer,
        p_portlet_id in integer
    ) return wwa_api_lovvalues

  Not currently used.

  Parameters:
    `p_provider_id` - the provider ID
    `p_portlet_id` - the portlet ID
  Returns:
    object of type wwa_api_lovvalues
  Since:
    Oracle Portal 3.0.9

### get_target

    procedure get_target(
        p_target in out varchar2,
        p_target_mode in out varchar2
    )

  Gets the target URL and target mode of a form component.

  Note: To set these values, use the set_target procedure.

  Example:

         declare
             l_target varchar2(2000);
             l_target_mode varchar2(100);
         begin
             portal_schema.wwa_app_module.get_target
             (
                 p_target        => l_target,
                 p_target_mode   => l_target_mode
             );
         end;

  Parameters:
    `p_target` - the URL to be displayed
    `p_target_mode` - determines whether the current session is dropped. The options are CALL and GO:
    GO - the current session is dropped before going to the URL.
    CALL - the current session is not dropped so you can return to previous session.
  Since:
    Oracle Portal 3.0.9

### help

    procedure help(
        p_module_id in number
    )

  Displays help text associated with a form component.

  Example:

        portal_schema.wwa_app_module.help
        (
             p_module_id => 1080540748
        );

  Parameters:
    `p_module_id` - the module ID of the form component
  Since:
    Oracle Portal 3.0.9

### is_portlet_runnable

    function is_portlet_runnable(
        p_portlet_instance in wwpro_api_provider.portlet_instance_record
    ) return boolean

  Checks if a portlet can be contacted. Use this function to test if a portlet can be reached. It returns true always.

  Example:

             declare
                  l_portlet_inst_rec wwpro_api_provider.portlet_instance_record;
                  l_result boolean;
              begin
                  l_result := wwa_app_module.is_portlet_runnable(
                      l_portlet_inst_rec);
              end ;

  Parameters:
    `p_portlet_instance` - record of type wwpro_api_provider.portlet_instance_record
  Returns:
    true always when the portlet is contactable
  Since:
    Oracle Portal 3.0.9
  See Also:
    wwpro_api_provider.portlet_instance_record

### link

    procedure link(
        p_arg_names in wwv_utl_api_types.vc_arr default empty_vc_arr,
        p_arg_values in wwv_utl_api_types.vc_arr default empty_vc_arr
    )

  Starts a form component session via a link. Appropriate parameters can be passed as name value pairs.

  Note: Knowing the parameter names is important and this is illustrated in several examples. See Examples-wwa_app_module.link procedure.

  Parameters:
    `p_arg_names` - the argument name
    `p_arg_values` - a corresponding argument value
  Since:
    Oracle Portal 3.0.9

### new_instance

    procedure new_instance(
        p_moduleid in number
    )

  Creates a new session for a form component.

  This is the starting point for running a form component in full page mode. This procedure starts a new session for a given p_moduleid and then control is transferred to the show procedure with the session_id of the session. This URL starts a new session for a form component:

       http://HOST:PORT/pls/DAD/PORTAL_SCHEMA.wwa_app_module.new_instance?
       p_moduleid=MODULE_ID

  Where HOST, PORT, DAD, PORTAL_SCHEMA should be replaced with the appropriate values.

  Example:
  Consider a form component with module ID 1080540748. To start a session for this component, enter the following URL in a browser:

       http://HOST:PORT/pls/DAD/PORTAL_SCHEMA.wwa_app_module.new_instance?
       p_moduleid=1080540748

  The above URL displays a:
  - form based on a table/view in Query and Insert mode
  - master-detail form in Query and Save mode
  - form based on a procedure in Submit mode.

  The above URL can also be used to form an anchor tag which can start a session when a user clicks on the link.

  Parameters:
    `p_moduleid` - the module ID of the form component. This value can be obtained from the 'Run' or 'About' link on the form's Manage screen. For example, this is a typical Run link (where p_moduleid is 1080540748): PORTAL_SCHEMA.wwa_app_module.new_instance?p_moduleid=1080540748
  Since:
    Oracle Portal 3.0.9

### register_portlet

    procedure register_portlet(
        p_portlet_instance in wwpro_api_provider.portlet_instance_record
    )

  Not currently used.

  Parameters:
    `p_portlet_instance` - record of type wwpro_api_provider.portlet_instance_record
  Since:
    Oracle Portal 3.0.9

### set_target

    procedure set_target(
        p_target in varchar2,
        p_target_mode in varchar2 default 'call'
    )

  Sets the target URL for a form component.

  Example:
  Consider a procedure named helloworld in your database provider (application) schema, denoted by 'x'. Execute privileges have been granted on procedure helloworld to [portal_schema]_public database user:

         procedure helloworld
         (
             p_back_url in varchar2 default null
         )
         is
         begin
               htp.p('Hello World');
           if p_back_url is not null then
               htp.br;
               htp.p('<a href="'||p_back_url||'">Back to form</a>');
           end if;
         end;

  To set the target of the form component using the set_target procedure, make the call to set_target from one of the PL/SQL button handler codes:
  - Since the session is dropped when the target mode is GO, there is no need to give a Back link to the previous form session:

          portal_schema.wwa_app_module.set_target
          (
              p_target        =>'http://host:port/pls/dad/x.helloworld'
              p_target_mode   => 'GO'
          );

  - The current session is not dropped when the target mode is CALL, so we can give a Back link to the previous session:

          portal_schema.wwa_app_module.set_target
          (
            p_target      => 'http://host:port/pls/dad/x.helloworld?
                            p_back_url='||portal_schema.wwutl_htf.url_encode(
                            'http://host:port/pls/dad/portal_schema.'||
                            'wwa_app_module.show?p_sessionid='||p_session.get_id),
            p_target_mode => 'CALL'
           );

  Parameters:
    `p_target` - the URL to be displayed
    `p_target_mode` - determines whether the current session is dropped. The options are CALL and GO:
    GO - the current session is dropped before going to the URL.
    CALL - the current session is not dropped so you can return to previous session.
  Since:
    Oracle Portal 3.0.9

### show

    procedure show(
        p_sessionid in number default null,
        p_regionid in number default null,
        p_portletid in number default null,
        p_header in varchar2 default 'true'
    )

  Displays a form component.

  The session ID can be obtained from the HTML source of the form component, i.e. it appears as a hidden variable named p_session_id. When a form component is run in full page mode, the session ID can be obtained from the browser, where the URL format would be:

       http://HOST:PORT/pls/DAD/PORTAL_SCHEMA.wwa_app_module.show?
       p_sessionid=341

  Example:
  Consider a form component with session ID 341. There are two ways to display this form component, by either:

  - Calling the procedure:

          portal_schema.wwa_app_module.show
          (
               p_sessionid => 341
           );

  - Entering the following URL in a browser:

         http://HOST:PORT/pls/DAD/PORTAL_SCHEMA.wwa_app_module.show?
         p_sessionid=341

  Parameters:
    `p_sessionid` - the ID of the session. The ID is created by either the new_instance or show_portlet procedures. This form component session can only be accessed from the Oracle Portal session that created it. It cannot be shared amongst other Portal sessions.
    `p_regionid` - not currently used
    `p_portletid` - not currently used
    `p_header` - not currently used
  Since:
    Oracle Portal 3.0.9

### show_portlet

    procedure show_portlet(
        p_portlet_record in out wwpro_api_provider.portlet_runtime_record
    )

  Displays a form component as a portlet on a page. The provider calls this procedure along with the portlet runtime record.

  Example:
  Consider a procedure that declares a local variable of the type wwpro_api_provider.portlet_runtime_record and populates the fields of the record with appropriate values. To display the form component as a portlet, call:

       portal_schema.wwa_app_module.show_portlet
       (
         p_portlet_record =>l_portlet_record
        );

  Parameters:
    `p_portlet_record` - a portlet_runtime_record
  Since:
    Oracle Portal 3.0.9

Overview | Package | Object Type | Deprecated | Index | Help
| Oracle Application Server Portal PL/SQL API Reference - 10.1.4
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES
SUMMARY: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE | DETAIL: EXCEPTION | TYPE | CONSTANT | VARIABLE | FUNCTION/PROCEDURE