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

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