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 wwpro_api_parameters

This package contains procedures and functions to get the values of portlet parameters.

Portlets use this API to retrieve any read-only parameters that have been passed into the URL of the current page.

Portlets obtain their parameters by calling a parameter API. Parameter values are stored by the invoking page as a series of name-value (N-V) pairs. Parameters that have more than one value are represented by N-V pairs with the same name and different values. Requests for parameter values will return one or more values (depending on the values stored and the method used) in the order in which they were setup. In retrieval, value order is maintained.

  • Parameter names are case insensitive.
  • Parameter values are case sensitive.
  • Parameters can use scoped names.

The URL may contain multiple parameters with the same name. In this case a parameter is a assigned to the portlet using the reference path as it uniquely identifies the portlet instance on the page. The scoping information of the reference path can be used to target parameter values to individual portlets within a page.

Example: If portlets with the reference paths 'ref1' and 'ref2' are displayed on a given page, and if the following parameters are passed to the portlets through the URL:

  • deptno = 10
  • ref1.deptno = 20
  • ref1.empno = 30

then these results are returned for the calls to the get_value API:

  • wwpro_api_parameter.get_value('deptno','ref1') returns 20
  • wwpro_api_parameter.get_value('deptno','ref2') returns 10
  • wwpro_api_parameter.get_value('empno','ref2') returns an empty list

Comments:

  • Parameter values found at a tighter scope replace values at a looser scope. A tightly scoped parameter is one that is fully specified. An example for the deptno parameter is [referencepath].deptno. An example of a loosely scoped parameter is deptno without a reference path.
  • If the URL contains both types of parameters and if the requester uses a reference path, the parameter at the tighter of the two bindings (i.e., [referencepath].deptno) is returned.
  • In the first example call, the result is '20' because in the URL the parameter is fully specified as ref1.deptno and the value is set to '20'.
  • In the second example call, there is no parameter deptno specified for portlet with reference path 'ref2', so the parameter is checked at a looser (global) scope. The value of deptno at the looser scope is '10', so the result is '10'.
  • In the third example call, there is no empno parameter with reference path 'ref2' specified for portlet . Even if a check is done one level up at a looser (global) scope, there is no such parameter, so the API returns an empty list.


Scope:
Public
Since:
Oracle Portal 3.0.6.6.5



Function/Procedure Summary
get_names
Returns a list of parameter names, given the portlet's reference path.
 owa.vc_arr
get_value
Returns the scalar value of a parameter, given the parameter name and reference path.
 varchar2
get_values
Returns all the values associated with a single parameter name.
 owa.vc_arr
get_values
Returns all the values associated with a list of parameter names.
 owa.vc_arr
retrieve
Retrieves a list of all the URL parameters (names and values) from every portlet instance that belongs to a provider.
 
retrieve
Retrieves a list of all the URL parameters (names and values), unchanged.
 wwpro_values

Function/Procedure Detail

get_names

function  
      
get_names(
    p_reference_path in varchar2
) return owa.vc_arr
    
Returns a list of parameter names, given the portlet's reference path. If no names are found, an empty list is returned.

Any user can use this function.

Example:

If a URL has these parameters:

   http://.......?empno=10&deptno=10&ref1.deptno=20&ref1.deptno=25&ref1.folderid=30

where 'ref1' is the reference path of the portlet instance.

Then this call:

   l_names owa.vc_arr;
   l_names := wwpro_api_parameters.get_names
   (
       p_reference_path => p_portlet_runtime_record.reference_path
   );

Returns:

   deptno and folderid in l_names
Parameters:
p_reference_path - a unique identifier for a portlet instance on the current page. The reference_path is passed to the portlet's show procedure in the portlet_runtime_record.
Returns:
an ordered list of parameter names for a given reference path or and empty list if no parameters were found for that reference path
Since:
Oracle Portal 3.0.6.6.5

get_value

function  
      
get_value(
    p_name in varchar2,
    p_reference_path in varchar2
) return varchar2
    
Returns the scalar value of a parameter, given the parameter name and reference path. If more than one value exists for the specified parameter, only the first is returned.

Any user can use this function.

Notes:

A scalar value is a single number, value, or data item, as opposed to a vector, matrix, or array (which contain multiple values).

The reference path identifies a portlet instance on a page and can be used to target parameters to an individual portlet or to groups of portlets on a given page.

Example:

If a URL has these parameters:

   http://.......?empno=10&empno=25&deptno=10&ref1.deptno=20&ref1.empno=30

Then this call:

   l_value varchar2;
   l_value := wwpro_api_parameters.get_value
   (
       p_name           => 'empno',
       p_reference_path => p_portlet_runtime_record.reference_path
   );

Returns:

   l_value = '30'
Parameters:
p_name - the name of the parameter to be returned
p_reference_path - a unique identifier for a portlet instance on the current page. The reference_path is passed to the portlet's show procedure in the portlet_runtime_record.
Returns:
the first value of the specified parameter, or null if the parameter is not found or invalid
Since:
Oracle Portal 3.0.6.6.5

get_values

function  
      
get_values(
    p_name in varchar2,
    p_reference_path in varchar2
) return owa.vc_arr
    
Returns all the values associated with a single parameter name.

To return values associated with a list of parameter names, call get_values function (multiple parameter names).

Any user can use this function.

Example:

If a URL has these parameters:

http://......?empno=10&deptno=10&ref1.deptno=20&ref1.deptno=25&ref1.folderid=30

where 'ref1' is the reference path of the portlet instance.

Then this call:

   l_values owa.vc_arr;
   l_values := wwpro_api_parameters.get_values
   (
       p_name           => 'depno',
       p_reference_path => p_portlet_runtime_record.reference_path
   );

Returns:

   20 and 25 for l_values.
Parameters:
p_name - the name of the portlet parameter
p_reference_path - a unique identifier for a portlet instance on the current page. The reference_path is passed to the portlet's show procedure in the portlet_runtime_record.
Returns:
a list of parameter values, or an empty list if no matches are found
Since:
Oracle Portal 3.0.6.6.5

get_values

function  
      
get_values(
    p_names in owa.vc_arr,
    p_reference_path in varchar2
) return owa.vc_arr
    
Returns all the values associated with a list of parameter names.

To return values associated with a single parameter name, call get_values function (single parameter name).

Any user can use this function.

Example:

If a URL has these parameters:

   http://.......?empno=10&deptno=10&ref1.deptno=20&ref1.deptno=25&ref1.folderid=30

where 'ref1' is the reference path of the portlet instance.

and if:

   l_names contains 'deptno' and 'folderid'

Then this call:

   l_values owa.vc_arr;
   l_names owa.vc_arr;
   l_values := wwpro_api_parameters.get_values
   (
       p_names          => l_names,
       p_reference_path => p_portlet_runtime_record.reference_path
   );

Returns:

   20, 25, and 30 for l_values
Parameters:
p_names - the names of the portlet parameters
p_reference_path - a unique identifier for a portlet instance on the current page. The reference_path is passed to the portlet's show procedure in the portlet_runtime_record.
Returns:
a list of parameter values, or an empty list if no matches are found
Since:
Oracle Portal 3.0.6.6.5

retrieve

procedure  
      
retrieve(
    p_names in out owa.vc_arr,
    p_values in out owa.vc_arr
)
    
Retrieves a list of all the URL parameters (names and values) from every portlet instance that belongs to a provider.

The names and values are returned, unchanged, into a table. If a parameter has more than one value, only the first is returned.

Any user can use this procedure.

Example:

If a URL has these parameters:

   http://.......?empno=10&deptno=10&ref1.deptno=20&ref1.deptno=25&ref1.folderid=30

Then this call:

   wwpro_api_parameters.retrieve
   (
       l_names,
       l_values
   );

Sets the following names and values:

  'empno', 'deptno', 'ref1.deptno', 'ref1.deptno', 'ref1.folderid'
  in l_names and '10', '10', '20', '25', '30' in l_values
Parameters:
p_names - the names of the parameters, unchanged, in the specified table
p_values - the values of the parameters into the specified table
Since:
Oracle Portal 3.0.6.6.5

retrieve

function  
      
retrieve
return wwpro_values
    
Retrieves a list of all the URL parameters (names and values), unchanged. The parameters are returned in a table of object_type wwpro_value.

Any user can use this function.

Note: This is an internal API.

Example:

   l_pro_values wwpro_values;
   l_pro_values := wwpro_api_parameters.retrieve;
Returns:
all the parameters in a wwpro_values table
Since:
Oracle Portal 3.0.6.6.5

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