Implementing a Session Store

8-22 Oracle Fusion Middleware Developers Guide for Oracle Portal ex_counter || p_portlet_record.reference_path; if ex_counter is null then -- first invocation session_parms.set_attribute ex_counter || p_portlet_record.reference_path,1; ex_counter := session_parms.get_attribute_as_number ex_counter || p_portlet_record.reference_path; else -- on every invocation increase by 1 ex_counter := ex_counter + 1; session_parms.set_attribute ex_counter || p_portlet_record.reference_path, ex_counter; end if; session_parms.save_session; ... end show_contents; 4. Optionally, if you want to see this portlet on a page and it is not already in the Portlet Repository, refer to the instructions in Section 8.3.2, Implementing the Provider Package for information on how to add it. 5. Once your portlet appears in the repository, you can add it to a page to test it. To add your portlet to a page, follow the instructions in Oracle Fusion Middleware Users Guide for Oracle Portal.

8.5 Using Parameters

The functionality of portlets can be extended with the help of parameters. The business logic implemented by portlets may produce different HTML output depending on the parameters passed to the page. By using portlet parameters, you can navigate within the portlet in Shared Screen mode without changing the current page. Portlets can also communicate with each other through parameters. Portlet parameters are structured as name-value pairs. These pairs map directly to the URL parameter passing format by using the GET submission method or can use the HTTP message body by using the POST submission method. Portlets can also expose their parameters to Oracle Portal. When added to a page, these portlets can accept values in the form of page parameters created by the page designer. Portlets do not have direct access to the URL, the HTTP message body, or the page parameters. To retrieve the parameter values, portlets must call the Oracle Portal PLSQL parameter APIs provided in the wwpro_api_parameters package. Oracle Portal offers the following types of parameters: ■ Private portlet parameters enable the implementation of internal navigation in your portlet. Note: Portlet parameter names should not start with an underscore _ because those parameters are reserved for internal use by Oracle Portal and are not passed to the portlet. Caution: You cannot mix the usage of public and private parameters in a portlet. To enable public parameters for your portlet, you must take steps that preclude the usage of private parameters and vice versa. Creating PLSQL Portlets 8-23 ■ Public portlet parameters let you pass control over the data flow of your portlet to the page designer. The page designer can map the public portlet parameters to their page parameters, provide default values, and allow users to personalize those values. ■ Page parameters are defined in a simple user interface by page designers. These page parameters can be mapped to public portlet parameters in order for the page designer to pass parameter values from the page to the portlets on it. For more information about parameters, refer to Section 2.12, Public Portlet Parameters Support and Section 2.13, Private Portlet Parameter Support .

8.5.1 Passing Private Parameters

You can use either GET or POST HTML submission methods when passing private portlet parameters. The GET method uses the URL to pass the parameters, whereas the POST method places the parameters in an HTTP message body. For both methods, you must specify the portlet instance on the portal page, how the parameter is called, and the value of the parameter. There are the following two types of private portlet parameters: ■ Qualified parameters ensure that a private portlet parameter is not read by any other portlet on the page. The reference path, which is assigned when the portlet is added to a page, is the unique prefix of the parameter. For example, http:page_url?277_MAP_368673.region=Europe. The qualified parameters reference path is 277_MAP_368673, the name is region, and the value is Europe. For private parameters, we strongly recommend that you always use qualified parameters. ■ Unqualified parameters have no information about the portlet instance and can be read by any portlet on the page. For example, http:page_ url?region=Europe. The unqualified parameters name is region and its value is Europe. For private parameters, we strongly recommend that you avoid unqualified parameters.

8.5.2 Passing Page Parameters and Mapping Public Portlet Parameters

Public portlet parameters enhance the flexibility of your portlets by enabling page designers to reuse your portlets on multiple pages. As a result, page designers do not have to ask you to make changes to the portlet code when adding the portlet to different pages. By using public portlet parameters, any portlet on a page can easily receive its value from the mapped page parameter, regardless of the portlet parameter name. For example, suppose you have a page parameter named dept_id. Three portlets need this value, but one portlet calls it dept, another calls it deptno, and still another department_id. Mapping the page parameter enables all three portlets to receive the value from the dept_id parameter and place it in the appropriate portlet parameter. Furthermore, the page designer may set a default value for example, department 20 that can be personalized by users for example, department 30 and applied to all three portlets. The general model for passing public and page parameters is as follows: 1. Enable public parameters in the portlet record by setting pass_all_url_params to false. This ensures that the portlet is only passed parameters intended for that portlet. 8-24 Oracle Fusion Middleware Developers Guide for Oracle Portal 2. Declare the public parameters in the providers describe_portlet_ parameters function. For each of the portlets that belong to the provider, this procedure should return a list of the parameters that the portlet accepts in the form of a PLSQL table of records of the type: type portlet_parameter_table is table of portlet_parameter_record index by binary_integer; 3. Provide descriptive information for the parameters in the portlets describe_ parameters function. For example: function describe_parameters p_provider_id in integer, p_language in varchar2 return wwpro_api_provider.portlet_parameter_table is l_params wwpro_api_provider.portlet_parameter_table; begin l_params1.name := dept_id; l_params1.datatype := wwpro_api_provider.STRING_TYPE; l_params1.description := Defines a department ID; l_params1.display_name := Department ID; return l_params; end describe_parameters; 4. Assign values to the public parameters. Public parameters typically get their values through page parameters. Page parameters are usually assigned default values by the page designer and the user can then personalize the value at runtime. Alternatively, page parameter values can be assigned in the calling URL. For more information about how page designers can use page parameters, refer to the Oracle Fusion Middleware Users Guide for Oracle Portal.

8.5.3 Retrieving Parameter Values

Regardless of whether you are using private or public parameters, you use the same APIs to retrieve their values. Portlets obtain their parameters by calling the following PLSQL parameter APIs in the wwpro_api_parameters package: ■ wwpro_api_parameters.get_value returns the parameter value that is specified by a given parameter name. Parameter names are not case sensitive, whereas parameter values are case sensitive. For example: l_region := wwpro_api_parameters.get_value p_name = region, p_reference_path = p_portlet_record.reference_path; ■ wwpro_api_parameters.get_values returns an array of parameter values. This function returns all the values that are associated with a single parameter name or an empty list if no matches are found. Some business logic may require multiple selections, when multiple values are passed to the portlet by using the same parameter name. Portlets can take one or more values of the same parameter. For example: l_region_values owa.vc_arr; ... l_region_values := wwpro_api_parameters.get_values p_name = region, p_reference_path = p_portlet_record.reference_path;