Building Links with the Portlet URL Types To build links with the URL

Enhancing Java Portlets 7-19 linkParams, true, true li } ul center

7.2.3.3.3 Building Forms with the Portlet URL Types Use of portlet parameters in forms is

little different from links. The following two fundamental rules continue to apply: ■ Qualify the portlets parameter names. ■ Do not manipulate or remove the other parameters on the incoming URL. In terms of markup and behavior, forms and links differ quite considerably. However, just as with links, PDK-Java contains utilities for complying with these two basic rules. The code for properly qualifying the portlets parameter name is the same as described in Section 7.2.3.3.2, Building Links with the Portlet URL Types . After all, a parameter name is just a string, whether it be a link on a page or the name of a form element. Forms differ from links in the way you ensure that the other parameters in the URL remain untouched. Once you open the form in the markup, you can make use of one of the following APIs: UrlUtils.htmlFormHiddenFieldspRequest,UrlUtils.PAGE_LINK, formName; UrlUtils.htmlFormHiddenFieldssomeURL; where formName = UrlUtils.htmlFormNamepRequest,null. The htmlFormHiddenFields utility writes HTML hidden form elements into the form, one form element for each parameter on the specified URL that is not owned by the portlet. INPUT TYPE=hidden name=paramName value=paramValue Thus, the developer needs only to add their portlets parameters to the form. The other item of which you need to be aware is how to derive the submission target of your form. In most cases, the submission target is the current page: formTarget = UrlUtils.htmlFormActionLinkpRequest,UrlUtils.PAGE_LINK The value of formTarget can be the action attribute in an HTML form or the target attribute in a SimpleForm. Even though the method name includes HTML, it actually just returns a URL and thus you can use it in mobile portlets, too. The following example form renders the thesaurus portlets submission form. Refer to the example in Section 7.2.3.3.2, Building Links with the Portlet URL Types for the portlet that results from the submission of this form. Note: Just as parameters in URLs and element names in forms require qualification to avoid clashing with other portlets on the page, form names must be fully qualified because any given page might have several forms on it. 7-20 Oracle Fusion Middleware Developers Guide for Oracle Portal String paramNameSubmit = submit; String paramNameQ = q; String qualParamNameQ = HttpPortletRendererUtil.portletParameterparamNameQ; String qualParamNameSubmit = HttpPortletRendererUtil.portletParameterparamNameSubmit; PortletRenderRequest pRequest = PortletRenderRequest request.getAttributeHttpCommonConstants.PORTLET_RENDER_REQUEST; String formName = UrlUtils.htmlFormNamepRequest,query_form; -- Output the HTML content -- center bThesaurusb Enter the word you wish to search for form name== formName method=POST action== UrlUtils.htmlFormActionLinkpRequest,UrlUtils.PAGE_LINK = UrlUtils.htmlFormHiddenFieldspRequest,UrlUtils.PAGE_LINK, formName tabletrtd Word of interest: tdtd input type=text size=20 name== qualParamNameQ value= tdtrtable input type=submit name== qualParamNameSubmit Value=Search form center

7.2.3.3.4 Implementing Navigation within a Portlet You can implement navigation within a

portlet in one of three ways, as follows: ■ Pass navigation information in rendered URLs using explicit portlet parameters. Branching logic within the portlet code then determines which section of the portlet to render based on the URL. This option represents a small extension to the thesaurus example presented in Section 7.2.3.3.2, Building Links with the Portlet URL Types and Section 7.2.3.3.3, Building Forms with the Portlet URL Types . Basically, instead of performing thesaurus search operations using the value of parameter q, the portlet branches based on the parameter value and renders different content accordingly. ■ Pass navigation information as described in the previous item but use PDK-Java to interpret the parameter and thus branch on its value. This option requires some further changes to the thesaurus example and is more fully explained subsequently. ■ Use session storage to record the portlet state and URL parameters to represent actions rather than explicit navigation. This method provides the only way that you can restore the portlet to its previous state when the user navigates off the page containing the portlet. Once the user leaves the page, all portlet parameters are lost and you can only restore the state from session storage, assuming you previously stored it there. This option requires that you understand and implement session storage. Refer to Section 7.2.6.2, Implementing Session Storage for more information about implementing session storage. The following portlet code comes from the multi-page example in the sample provider of PDK-Java: Enhancing Java Portlets 7-21 portlet id11id nameMultipagename titleMultiPage Sampletitle shortTitleMultiPageshortTitle description This portlet depicts switching between two screens all in the context of a Portal page. description timeout40timeout timeoutMessageMultiPage Sample timed outtimeoutMessage renderer class=oracle.portal.provider.v2.render.RenderManager contentTypetexthtmlcontentType showPagehtdocsmultipagefirst.jspshowPage pageParameterNamenext_pagepageParameterName renderer portlet Notice that the value of pageParameterName is the name of a portlet parameter, next_page, that the PDK framework intercepts and interprets as an override to the value of the showPage parameter. If the PDK framework encounters the qualified version of the parameter when the multi-page portlet is requested, it will render the resource identified by next_page rather than first.jsp. Note that the PDK does not render the parameter within the portlet, that responsibility falls to the portlet. You can modify the thesaurus example to operate with the use of this parameter. Specifically, you can use the form submission portlet to be the input for the thesaurus the first page of the portlet, then navigate the user to the results page, which contains links to drill further into the thesaurus. The following examples illustrate these changes. ThesaurusForm.jsp: PortletRenderRequest pRequest = PortletRenderRequest request.getAttributeHttpCommonConstants.PORTLET_RENDER_REQUEST; String paramNameSubmit = submit; String paramNameQ = q; String qualParamNameQ = HttpPortletRendererUtil.portletParameterpRequest, paramNameQ; String qualParamNameSubmit = HttpPortletRendererUtil.portletParameterpRequest, paramNameSubmit; String formName = UrlUtils.htmlFormNamepRequest,query_form; -- Output the HTML content -- center bThesaurusb Enter the word you wish to search for form name== formName method=POST action== UrlUtils.htmlFormActionLinkpRequest,UrlUtils.PAGE_LINK = UrlUtils.htmlFormHiddenFieldspRequest,UrlUtils.PAGE_LINK, formName Note: The example that follows is most useful for relatively simple cases, such as this thesaurus example. If your requirements are more complex for example, you want to build a wizard experience, then you should consider using an MVC framework such as Struts. For information on how to build portlets from struts applications, refer to Section 7.3, Building Struts Portlets with Oracle JDeveloper .