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

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

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

See Also:

wwv_utl_api_types.vc_arr

Since:

Oracle Portal 3.0.9

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

See Also:

wwpro_api_provider.portlet_instance_record

Since:

Oracle Portal 3.0.9

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