Creating and Accessing a Preference Store

8-18 Oracle Fusion Middleware Developers Guide for Oracle Portal function get_default_preference ... begin -- -- Try to find a previously entered portlet instance string preference, -- if any. -- A portlet instance string preference is stored in the preference -- store and has a level of SYSTEM_LEVEL_TYPE. -- p_path = PORTLET_PATH || p_reference_path, l_prefs.string_id := to_charwwpre_api_value.get_value_as_number p_name = PREFNAME_STRING, p_level_type = wwpre_api_value.SYSTEM_LEVEL_TYPE ; -- -- If the value returned above is null it is an indication that there -- is no default string yet. Initialize the string id to 0 to indicate -- this and load the default string value. -- if l_prefs.string_id is null or to_numberl_prefs.string_id = 0 then wwpre_api_value.set_value_as_number p_path = PORTLET_PATH || p_reference_path, p_name = PREFNAME_STRING, p_level_type = wwpre_api_value.SYSTEM_LEVEL_TYPE, p_level_name = null, p_value = 0 ; ... end get_default_preference; 5. Find the show procedure. Notice the behavior when the portlet is in Edit Defaults or Edit mode. Note also how p_action is populated when the user clicks APPLY, CANCEL , or OK. Once the form is submitted, the show procedure of the portlet is called again and, if the p_action parameter is not null, then the save_prefs procedure is called to save the personalizations and redirect to the relevant page. procedure show p_portlet_record wwpro_api_provider.portlet_runtime_record is l_str varchar232000; l_pref_record preference_record; l_action varchar210; l_names owa.vc_arr; l_values owa.vc_arr; begin ... elsif p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW_EDIT or p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW_EDIT_DEFAULTS then wwpro_api_parameters.retrievel_names, l_values; for i in 1..l_names.count loop if upperl_namesi = upperp_string then l_pref_record.string := l_valuesi; elsif l_namesi = p_title then l_pref_record.title_string := l_valuesi; elsif l_namesi = p_action then Creating PLSQL Portlets 8-19 l_action := l_valuesi; end if; end loop; if l_action in ACTION_OK,ACTION_APPLY,ACTION_CANCEL then if p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW_EDIT then save_prefsp_string = l_pref_record.string, p_title = l_pref_record.title_string, p_action = l_action, p_level = wwpre_api_value.USER_LEVEL_TYPE, p_portlet_record = p_portlet_record; else save_prefsp_string = l_pref_record.string, p_title = l_pref_record.title_string, p_action = l_action, p_level = wwpre_api_value.SYSTEM_LEVEL_TYPE, p_portlet_record = p_portlet_record; end if; else show_editp_portlet_record = p_portlet_record; end if; ... end show; 6. The show_edit procedure renders the page for Edit or Edit Defaults mode. It renders two text fields that allow the user to change the personalizable values in a form with three buttons Apply, OK, and Cancel. Note that this function uses the wwpro_api_adapter.open_form to create the HTML form with the correct action attribute for the FORM tag and with the correct hidden fields. It is important to use this procedure to create the FORM tag if you want to use the portlet with the Federated Portal Adapter from remote Oracle Portal instances. procedure show_edit p_portlet_record in wwpro_api_provider.portlet_runtime_record is l_prefs preference_record; l_text_prompt_string varchar230; l_title_prompt_string varchar230; begin ... htp.centeropen; htp.tableOpencattributes = BORDER=1 WIDTH=90; htp.tableRowOpen; htp.pTD; -- -- This procedure call creates the FORM tags with a set of -- standard parameters. Using this procedure makes the -- personalization page work through the plsql http adapter. -- wwpro_api_adapter.open_formp_formattr = NAME=services, p_prr = p_portlet_record; htp.pTD; htp.tableRowClose; htp.tableClose; htp.centerclose; htp.formclose; end show_edit; 8-20 Oracle Fusion Middleware Developers Guide for Oracle Portal 7. Review the following procedures and functions, which are related to the preference storage implementation in this example: ■ get_user_preference retrieves the user personalized string and title for the portlet. ■ save_prefs is invoked to save the preferences to the preference store when the user clicks OK or Apply after making personalization changes. ■ entered_text_is_valid checks to see if the text entered in the personalizable text fields is valid. 8. 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. 9. 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.4.2 Implementing a Session Store

The services example, located in ..\pdkplsql\pdk\plsql\svcex in PDK-PLSQL pdkplsql.zip, illustrates how you can implement a session store. The objective is to achieve the following functionality: ■ When a user invokes this portlet, it displays text that reads: This portlet has rendered x times in this session. x is the number of times the portlet has been rendered. ■ Every time the user invokes the portlet, the counter increases by 1. ■ Clicking Details in the portlet enables the user to reset the counter using Clear. After clearing the counter, the counter starts again from zero. Creating and Accessing a Session Store You can browse through this example as follows to see how to create the session store, store values in it, and retrieve values from it: 1. Open the services_portlet.pkb file in an editor. The domain and subdomain definitions for your session object are provided with aliases in the constants part of your portlet definition. DOMAIN constant varchar230 := provider; SUBDOMAIN constant varchar232 := services; PORTLET_PATH constant varchar2256:= oracle.portal.pdk.servicesportlet; PREFNAME_STRING constant varchar230 := services_string; PREFNAME_TITLE constant varchar230 := services_title; 2. Find the clear_count procedure. clear_count is called from the show procedure when the user clicks Clear to reset the counter. clear_count calls wwsto_api_session.load_session to load the session object. Then, it calls wwsto_api_session.set_attribute to set the counter to zero. Lastly, it saves the session object by calling save_session. procedure clear_count p_action in varchar2, p_back_url in varchar2, p_reference_path in varchar2 Creating PLSQL Portlets 8-21 is ex_counter integer; session_parms 1..wwsto_api_session; begin -- -- Clear the display counter. -- if p_action = ACTION_CLEAR then -- -- Load the session object that contains the display counter -- session_parms := 1..wwsto_api_session.load_session DOMAIN,SUBDOMAIN; ex_counter := session_parms.get_attribute_as_number ex_counter || p_reference_path; -- -- Reset the display counter. -- ex_counter := 0; session_parms.set_attribute ex_counter || p_reference_path, ex_counter; -- -- Save the changes to the database immediately to avoid any -- data consistency problems with the data stored in the -- session object. -- session_parms.save_session; end if; owa_util.redirect_urlcurl=p_back_url; end clear_count; 3. Find the show_contents procedure. show_contents is called from the show procedure to retrieve the counter, increment it by one, and save the value in the session store. Notice how it retrieves the session object to display the number of times the user has rendered the portlet. It also retrieves the counter value with get_attribute_as_number and increments the counter for every invocation of this procedure. procedure show_contents p_portlet_record wwpro_api_provider.portlet_runtime_record is l_prefs preference_record; session_parms 1..wwsto_api_session; ex_counter integer; l_portlet wwpro_api_provider.portlet_record; l_str varchar232000; begin -- -- In this mode a session counter is used to indicate -- the number of invocations of this portlet during the -- current session. The counter is stored in the session -- store. -- session_parms := 1..wwsto_api_session.load_sessionDOMAIN,SUBDOMAIN; ex_counter := session_parms.get_attribute_as_number 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.