From do-not-reply at jboss.org Wed Apr 28 11:59:55 2010 Content-Type: multipart/mixed; boundary="===============8285091940300783961==" MIME-Version: 1.0 From: do-not-reply at jboss.org To: gatein-commits at lists.jboss.org Subject: [gatein-commits] gatein SVN: r2880 - in portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Reference_Guide/en-US/modules: PortletDevelopment and 1 other directories. Date: Wed, 28 Apr 2010 11:59:54 -0400 Message-ID: <201004281559.o3SFxs9o022046@svn01.web.mwc.hst.phx2.redhat.com> --===============8285091940300783961== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: thomas.heute(a)jboss.com Date: 2010-04-28 11:59:53 -0400 (Wed, 28 Apr 2010) New Revision: 2880 Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Referen= ce_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Referen= ce_Guide/en-US/modules/PortletDevelopment/PortletBridge/ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Referen= ce_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Referen= ce_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Referen= ce_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Referen= ce_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_development= .xml Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Referen= ce_Guide/en-US/modules/PortletDevelopment.xml Log: JBEPP-276: Reference Guide Merging the PortletBridge reference guide Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Ref= erence_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.x= ml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml = (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml = 2010-04-28 15:59:53 UTC (rev 2880) @@ -0,0 +1,464 @@ + + +%BOOK_ENTITIES; +]> +
+ Bridge Configuration + + The 329 specification is aimed at making the developers life as easy as = possible with JSF+Portlet development. You will see below that there are mi= nimal settings to getting any JSF web application up and running in the Por= tal environment. + + + If you are starting from scratch, we highly recommend you use the . + +
+ Core Setup and Configuration +
+ portlet.xml + + The basic JSR-329 portlet configuration. + + = + + <portlet> + <portlet-name>yourPortletName</portlet-name> + <portlet-class> + javax.portlet.faces.GenericFacesPortlet + </portlet-class> + + <init-param> + <name>javax.portlet.faces.defaultViewId.view</name> + <value>/welcome.xhtml</value> + </init-param> + + <init-param> + <name>javax.portlet.faces.defaultViewId.edit</name> + <value>/jsf/edit.xhtml</value> + </init-param> + + <init-param> + <name>javax.portlet.faces.defaultViewId.help</name> + <value>/jsf/help.xhtml</value> + </init-param> + + + When preserveActionParams is set to TRUE, the bridge must maintain any= request parameters assigned during the portlet's action request. The reque= st parameters are maintained in the"bridge reque= st scope". When this attribute isn't present or is FALSE the act= ion's request parameters are only maintained for the duration of the portlet request scope. + + = + + <init-param> + <name>javax.portlet.faces.preserveActionParams</name> + <value>true</value> + </init-param> + +
+ = +
+ faces-config.xml + + The PortletViewHandler ensures that each JSF portlet instance is prope= rly namespaced. + + = + + <faces-config> + <application> + <view-handler> + org.jboss.portletbridge.application.PortletViewHandler + </view-handler> + <state-manager>org.jboss.portletbridge.application.Po= rtletStateManager</state-manager> + </application> + ... + +
+ = +
+ Facelets Configuration + + The following web.xml setting is only for Facelets based applications + +
+ web.xml + = + + <web-app xmlns=3D"http://java.sun.com/xml/ns/j2ee" + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://java.sun.com/xml/ns/j2ee htt= p://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" + version=3D"2.4"> + ... + <!-- This is optional parameters for a facelets based appli= cation --> + <context-param> + <param-name>org.ajax4jsf.VIEW_HANDLERS</param-nam= e> + <param-value>org.jboss.portletbridge.application.Fac= eletPortletViewHandler</param-value> + </context-param> + + + + = + + <context-param> + <param-name>javax.portlet.faces.RENDER_POLICY</pa= ram-name> + <param-value> + ALWAYS_DELEGATE + </param-value> + </context-param> + ... + </web-app> + + + RenderPolicy Options + + + + + ALWAYS_DELEGATE Indicates the bridge should no= t render the view itself but rather always delegate the rendering. + + + + + NEVER_DELEGATE Indicates the bridge should alw= ays render the view itself and never delegate. + + + + + DEFAULT Directs the bridge to first delegate t= he render and if and only if an Exception is thrown then render the view ba= sed on its own logic. If the configuration parameter is not present or has = an invalid value the bridge renders using default behavior. I.e. as if DEFA= ULT is set. + + + + + +
+ +
+ = +
+ JSP Only Configuration + + The following web.xml setting is only for JSP based applications. Down= load the demo application here. + +
+ web.xml + = + + <web-app xmlns=3D"http://java.sun.com/xml/ns/j2ee" + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://java.sun.com/xml/ns/j2ee htt= p://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" + version=3D"2.4"> + + <context-param> + <param-name>javax.portlet.faces.renderPolicy</par= am-name> + <param-value> + NEVER_DELEGATE + </param-value> + </context-param> + ... + </web-app> + +
+ +
+ = +
+ JSR-329 + + The Jboss Portlet Bridge can be used with a any compatible implementat= ion ( for example, MyFaces implementation). Simply put the following into w= eb.xml : + + = + + + <context-param> + <param-name>javax.portlet.faces.BridgeImplClass</param-na= me> + <param-value>org.apache.myfaces.portlet.faces.bridge.BridgeI= mpl</param-value> + </context-param> + +
+ +
+ = + +
+ RichFaces Setup and Configuration Options +
+ web.xml + + The following configuration is designated for portlets using the RichF= aces library. These settings will vary based on your individual needs. See = this section of the RichFaces documentation for mor= e details. + + + Sometimes it is better to use the "ALL" load strategy in portlets so y= ou do not need to worry about loading the "framework.pack.js" and "ui.pack.= js" files manually in your portlet header. + + = + + <context-param> + <param-name>org.richfaces.LoadStyleStrategy</para= m-name> + <param-value>ALL</param-value> + </context-param> + <context-param> + <param-name>org.richfaces.LoadScriptStrategy</par= am-name> + <param-value>ALL</param-value> + </context-param> + + + + If you use the "NONE" strategy, you must include the following script= s in your portlet or portal page header. If you are using JBoss Portal, you= can add this to the jboss-portlet.xml file. + + + + The org.ajax4jsf.RESOURCE_URI_PREFIX configuration = cross references the path to your scripts below. These settings are require= d for RichFaces using the "NONE" strategy. + + = + + <script src=3D"/faces/rfRes/org/ajax4jsf/framework.pack.js" type=3D= "text/javascript"></script> + <script src=3D"/faces/rfRes/org/richfaces/ui.pack.js" type=3D"text/= javascript"></script> + <link rel=3D"stylesheet" type=3D"text/css" href=3D"/faces/rfRes/org= /richfaces/skin.xcss"/> + + + Seam automatically configures your Ajax4JSF Filter, so if you are runn= ing a Seam portlet, you do not need the following Filter config. (But you d= o need the RESOURCE_URI_PREFIX no matter what) + + = + + <context-param> + <param-name>org.ajax4jsf.RESOURCE_URI_PREFIX</par= am-name> + <param-value>rfRes</param-value> + </context-param> + + <filter> + <display-name>Ajax4jsf Filter</display-name> + <filter-name>ajax4jsf</filter-name> + <filter-class>org.ajax4jsf.Filter</filter-class&g= t; + </filter> + + <filter-mapping> + <filter-name>ajax4jsf</filter-name> + <servlet-name>FacesServlet</servlet-name> + <dispatcher>FORWARD</dispatcher> + <dispatcher>REQUEST</dispatcher> + <dispatcher>INCLUDE</dispatcher> + </filter-mapping> + ... + </web-app> + +
+ = + +
+ = +
+ Seam Setup and Configuration Options +
+ Configuration + + The ExceptionHandler is used to clean Seam contexts and transactions a= fter errors. + + = + + <context-param> + <param-name>org.jboss.portletbridge.ExceptionHandler</pa= ram-name> + <param-value> + org.jboss.portletbridge.SeamExceptionHandlerImpl + </param-value> + </context-param> + + + If you are using this bridge version from 2.0.0.BETA through 2.0.0.CR1= , you must define the following web.xml parameter to use the JBoss Portlet = Bridge provided Seam Phase Listener. + This is done by the bridge automatically (if needed) in 2.0.0.FINAL. + + + + <context-param> + <param-name>javax.faces.LIFECYCLE_ID</param-name> + <param-value>SEAM_PORTLET</param-value> + </context-param> + +
+ +
+ = +
+ Portlet 2.0 Coordination + + One very important thing to note before using either of the following m= echanisms, is that you must have the proper 2.0 schema and xsd definition a= t the top of your portlet.xml. + + = + + <portlet-app xmlns=3D"http://java.sun.com/xml/ns/portlet/portlet-ap= p_2_0.xsd" + version=3D"2.0" + xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=3D"http://java.sun.com/xml/ns/portlet/port= let-app_2_0.xsd + http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"> + +
+ Sending and Receiving Events +
+ Configuration + + Just like with any portlet 2.0 event consumer and receiver, you must = define them in the portlet.xml. To see a working example, checkout the Seam= Booking Demo portlet. + + + You must also define the following init params in your portlet.xml. + + = + + </init-param> + <init-param> + <name>javax.portlet.faces.autoDispatchEvents</name> + <value>true</value> + </init-param> + <init-param> + <name>javax.portlet.faces.bridgeEventHandler</name> + <value>org.foo.eventhandler</value> + </init-param> + + + For now, you must dipatch the event in the JSF or Seam backing bean. = Future versions on the 2.0 bridge will automate the dispatching and consumi= ng of events. + + = + + if (response instanceof StateAwareResponse) { + StateAwareResponse stateResponse =3D (StateAwareResponse) response; + stateResponse.setEvent(Foo.QNAME, new Bar()); + } + + + Then you must also create the event handler class by implementing the= BridgeEventHandler interface to process the event payload. + + = + + public class BookingEventHandler implements BridgeEventHandler + { + public EventNavigationResult handleEvent(FacesContext context, Even= t event) + { + //process event payload here + } + + } + +
+ +
+ = +
+ Public Render Parameters +
+ Configuration + + Public Render Parameters (or PRPs) are one of the most powerful and s= imple Portlet 2.0 features. Several portlets (JSF or not) can share the sam= e render parameters. This feature can be use to present a cohesive UI to th= e user across all portlets on the page (i.e. using an employee ID to displa= y relative data). + + + The bridge maps a render parameter to a backing bean using settings i= n your faces-config.xml and portlet.xml. A clear and working example can be= found in the Seam Booking Demo portlet. + + + You must define the following init params in your portlet.xml. + + = + + <init-param> + <name>javax.portlet.faces.bridgePublicRenderParameterHandler&l= t;/name> + <value>org.foo.PRPHandler</value> + </init-param> + ... + <supported-public-render-parameter>myCoolPRP</supported-publi= c-render-parameter> + + + Create a managed bean and public-parameter-mappings in your faces-con= fig.xml. This should be a basic bean that you can bind the passed parameter= to a string with getter and setter. + + = + + <managed-bean> + <managed-bean-name>bookingPRP</managed-bean-name> + <managed-bean-class>your.class.Name</managed-bean-class&g= t; + <managed-bean-scope>session</managed-bean-scope> + </managed-bean> + + <application> + <application-extension> + <bridge:public-parameter-mappings> + <bridge:public-parameter-mapping> + <parameter>"the name of your portlet":hotelName</= parameter> + <model-el>#{bookingPRP.hotelName}</model-el> + </bridge:public-parameter-mapping> + </bridge:public-parameter-mappings> + </application-extension> + </application> + + + You must set the parameter in the JSF or Seam backing bean, if you ar= e providing one from your portlet. + + = + + if (response instanceof StateAwareResponse) { + StateAwareResponse stateResponse =3D (StateAwareResponse) response; + stateResponse.setRenderParameter("hotelName",selectedHotel.getName= ()); + } + + + Then you must also implement the BridgePublicRenderParameterHandler i= nterface to process any updates from the received parameter. + + = + + public void processUpdates(FacesContext context) + { + ELContext elContext =3D context.getELContext(); + BookingPRPBean bean =3D (BookingPRPBean) elContext.getELResolver().g= etValue(elContext, null, "bookingPRP"); + + if(null !=3D bean){ + //Do something with bean.getHotelName()); + } else { + + } + } + +
+ +
+ = +
+ Serving Your JSF Resources in a Portlet +
+ Configuration + + We have setup a few examples to show you how to use EL and a simple b= ean that will allow you to use the portlet resource serving mechanism withi= n a JSF portlet. + + + In ResourceBean.java, you can see a very sim= ple implementations of a Map object that uses the bridge to get and encode = a resource url served from the portlets web application. + + + So, when you have the normal "/images", "/styles" and other resource = folders in your web app, you can use the following EL expression to serve t= hem in your JSF application. + + = + + #{resource['/img/the-path-to-my-image.png']} + + + Just copy the ResourceBean.java code above, and add an entry to you f= aces-config.xml for the bean: + + = + + <managed-bean> + <managed-bean-name>resource</managed-bean-name> + <managed-bean-class>org.richfaces.demo.common.ResourceBean<= /managed-bean-class> + <managed-bean-scope>application</managed-bean-scope> + </managed-bean> + +
+ +
+ +
+ +
+ Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Ref= erence_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.= xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml= (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/gettingstarted.xml= 2010-04-28 15:59:53 UTC (rev 2880) @@ -0,0 +1,249 @@ + + +%BOOK_ENTITIES; +]> +
+ Getting started with JBoss Portlet Bridge + + JBoss Portlet Bridge not only gives you the ability to run JSF web appli= cations in a portlet, but also gives you the benefit of running supported J= Boss frameworks like Seam and RichFaces. + +
+ What's New in 2.0? +
+ Eventing + + The bridge considers a portlet event a model event. I.e. the event is = targeted to the applications data model not its view. As JSF events primari= ly concern its view, the bridge processes the portlet events manually, howe= ver provisions are made to make sure that any model changes that result fro= m processing the event are updated in the view. Since event payloads are ar= bitrarily complex, the manual processing of the data, though managed by the= bridge, is left to the (portlet) application to support. + + + See for details and examples. + +
+ = +
+ Portlet Served Resources + + The bridge deals with portlet served resources in one of two ways. If = the request is for a non-JSF resource, the bridge handles the request by ac= quiring a request dispatcher and forwarding the request to the named resour= ce. If the request is for a JSF resource, the bridge runs the full JSF life= cycle ensuring that data is processed and the resource (markup) is rendered. + + + See for details a= nd examples. + +
+ = +
+ Public Render Parameters + + The bridge automates the processing of public render parameters. A pub= lic render parameter can be mapped to an object's accessor (get/set method)= designed to handle a String representation of the value via a Faces ValueE= xpression. When a new public render parameter value is received in a reques= t, the bridge sets the value by calling the ValueExpression's setValue(). A= t the end of a request, if the current value of any mapped public render pa= rameter doesn't match the current incoming value, the bridge sets the new v= alue in an outgoing public render parameter (if feasible in the given phase= ). + + + See for details and examples. + +
+ +
+ = +
+ Bridge Frameworks and Extensions + + The JBoss Portlet Bridge currently supports JBoss Portal, GateIn, JSF 1= .2, JBoss Seam, and JBoss Richfaces. There are configurations that apply to= supporting each framework. See section for instructions. + + + The JBoss Portlet Bridge project is also actively developing extensions= , and to differentiate from just another "project" that has boring ol' "ext= ensions" we coined the term "Bridgelets" - because what would a project wit= h Java and JSF be without having "*let" on the end of it? Not very cool in = my opinion ;) With that said, in this current release we decided to bring a= ll of our bridgelets into the impl code base since they are critical in mos= t JSF portlet applications. Now it only takes a single line of configuratio= n to utilize these features. + +
+ Seam Bridgelets + + For example, the PortalIdentity seam component allows you to instantly= have SSO between Seam and GateIn or JBoss Portal. This extension is config= ured in your Seam application's components.xml file as follows. + + = + + <security:portal-identity authenticate-method=3D"#{authenticator.a= uthenticate}"/> + +
+ = +
+ RichFaces Bridgelets + + Richfaces does not account for multiple components on the same portal = page by default. This following web.xml renders all RichFaces component jav= ascript to be portal friendly. + + = + + <context-param> + <param-name>org.jboss.portletbridge.WRAP_SCRIPTS</param-n= ame> + <param-value>true</param-value> + </context-param> + + + + + + Don't forget that the bridge is still in Beta and so are any extensi= ons. If you would like to contribute to any part of this project, we encour= age you to be active on the user forum and bring iss= ues/enhancements to attention. + + + +
+ +
+ = +
+ Before you start + + Current version and compatibilty information can be easily located on t= he JB= PB wiki. Ensure you are using compatible versions of all integrated= frameworks before you begin. + + + JBoss Portal and GateIn provides it's latest distribution included in J= Boss Application Server. All of the guesswork has been eliminated so that y= ou can unzip and run the Portal with a few clicks. Get the latest here (ensure you choos= e the Portal + JBoss AS link) + + + Next, all that's left is to download the JBoss Portlet Bridge distribution and= cofigure your portlet to use the bridge. Or, you can run a provided archet= ype and deploy the generated= war in a few easy steps. This will also give you an empty project to play = around with or start from scratch. + + +
+ = +
+ Maven Archetypes + + This project utilizes Maven archetypes which al= low you get up and running with different flavors of the bridge quickly. = + + Available Archetypes + + + + + + + + + Archetype + + + Command + + + + + + + JSF 1.2 Basic + + + = +mvn archetype:generate + -DarchetypeGroupId=3Dorg.jboss.portletbridge.archetypes + -DarchetypeArtifactId=3D1.2-basic + -DarchetypeVersion=3D2.0.0.CR1 + -DgroupId=3Dorg.whatever.project + -DartifactId=3Dmyprojectname + -DarchetypeRepository=3Dhttp://repository.jboss.org/maven2/ + + + + + + RichFaces Basic + + + = +mvn archetype:generate + -DarchetypeGroupId=3Dorg.jboss.portletbridge.archetypes + -DarchetypeArtifactId=3Drichfaces-basic + -DarchetypeVersion=3D2.0.0.CR1 + -DgroupId=3Dorg.whatever.project + -DartifactId=3Dmyprojectname + -DarchetypeRepository=3Dhttp://repository.jboss.org/maven2/ + + + + + + Seam Basic (Modular EAR) + + + = +mvn archetype:generate + -DarchetypeGroupId=3Dorg.jboss.portletbridge.archetypes + -DarchetypeArtifactId=3Dseam-basic + -DarchetypeVersion=3D2.0.0.CR1 + -DgroupId=3Dorg.whatever.project + -DartifactId=3Dseamproject + -DarchetypeRepository=3Dhttp://repository.jboss.org/maven2/ + + + + + +
+ +
+ = +
+ Video Tutorials + + Episode 1: Getting Started = With The Bridge + + + Episode 2: Portlet 1.0 Adva= nced Seam and RichFaces + + + Episode 3: Seam and Portlet= 2.0 Eventing + + + Episode 4: Running the 2.0 = bridge on GateIn and deploy using JBoss Tools + + + Episode 5: GateIn JMX Metri= cs and Dashboard Demo + + + Check here for t= he latest videos. + + +
+ +
+ Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Ref= erence_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml = (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/overview.xml 2010-= 04-28 15:59:53 UTC (rev 2880) @@ -0,0 +1,82 @@ + + +%BOOK_ENTITIES; +]> +
+ JBoss Portlet Bridge Overview + + To get an idea of the JBoss Portlet Bridge community, the developers, an= d for wiki information, checkout the project page. + + + What is the JBoss Portlet Bridge? + + The JBoss Portlet Bridge (or JBPB for short) is a non-final draft imple= mentation of the JSR-3= 29 specification which supports the JSF 1.2 runtime within a JSR 28= 6 portlet and with added enhancements to support other web frameworks (such= as Seam and RichFaces). It allows an= y Java developer to get started quickly with their JSF web application runn= ing in a portal environment. The developer no longer needs to worry about t= he underlying portlet development, portlet concepts, or the API. + + + + Understanding how JSF works with Portal + + The portlet bridge isn't a portlet. It's the mediator between the two e= nvironments and allows JSF and Portal to be completely unaware of each othe= r. The bridge is used to execute Faces requests on behalf of the portlet. D= uring each request, the Faces environment is setup and handled by the bridg= e. Part of this implementation acts as a Faces controller much as the Faces= Servlet does in the direct client request world. The other part of this imp= lementation is provided by implementating a variety of (standard) Faces ext= ensions. + + + + + This draft specification for the JSR 329 specification is not final. A= ny final specification that may be published will likely contain difference= s, some of which may be substantial. Publication of this draft specificatio= n is not intended to provide the basis for implementations of the specifica= tion. This draft specification is provided AS IS, with all faults. THERE AR= E NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF CONDITION OF T= ITLE OR NONINFRINGEMENT. You may copy and display this draft specification = provided that you include this notice and any existing copyright notice. Ex= cept for the limited copyright license granted above, there are no other li= censes granted to any intellectual property owned or controlled by any of t= he authors or developers of this material. No other rights are granted by i= mplication, estoppel or otherwise. + + + +
+ Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Ref= erence_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_develop= ment.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_developmen= t.xml (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge/portlet_developmen= t.xml 2010-04-28 15:59:53 UTC (rev 2880) @@ -0,0 +1,311 @@ + + +%BOOK_ENTITIES; +]> +
+ Developing Portlets with the Bridge + + This chapter demonstrates common development tasks described by the 329 = specification. + +
+ Excluding Attributes from the Bridge Request Scope + + When your application uses request attributes on a per request basis an= d you do not want that particular attribute to be managed in the extended b= ridge request scope, you must use the following configuration in your faces= -config.xml. Below you will see that any attribute namespaced as foo.bar or= any attribute beginning with foo.baz(wildcard) will be excluded from the b= ridge request scope and only be used per that application's request. + + = + + <application> + <application-extension> + <bridge:excluded-attributes> + <bridge:excluded-attribute>foo.bar</bridge:excl= uded-attribute> + <bridge:excluded-attribute>foo.baz.*</bridge:ex= cluded-attribute> + </bridge:excluded-attributes> + </application-extension> + </application> + +
+ = +
+ Supporting PortletMode Changes + + A PortletMode represents a distinct render path within an application. = There are three standard modes: view, edit, and help. The bridge's External= Context.encodeActionURL recognizes the query string parameter javax.portlet= .faces.PortletMode and uses this parameter's value to set the portlet mode = on the underlying portlet actionURL or response. Once processed it then rem= oves this parameter from the query string. This means the following navigat= ion rule causes one to render the \edit.jspx viewId in the portlet edit mod= e: + + = + + <navigation-rule> + <from-view-id>/register.jspx</from-view-id> + <navigation-case> + <from-outcome>edit</from-outcome> + <to-view-id>/edit.jspx?javax.portlet.faces.PortletMode= =3Dedit</to-view-id> + </navigation-case> + </navigation-rule> + +
+ = +
+ Navigating to a mode's last viewId + + By default a mode change will start in the mode's default view without = any (prior) existing state. One common portlet pattern when returning to th= e mode one left after entering another mode (e.g.. view -> edit -> vi= ew) is to return to the last view (and state) of this origin mode. The brid= ge will explicitly encode the necessary information so that when returning = to a prior mode it can target the appropriate view and restore the appropri= ate state. The session attributes maintained by the bridge are intended to = be used by developers to navigate back from a mode to the last location and= state of a prior mode. As such a developer needs to describe a dynamic nav= igation: "from view X return to the last view of mode y". This is most easi= ly expressed via an EL expression. E.g. + + = + + <navigation-rule> + <from-view-id>/edit.jspx*</from-view-id> + <navigation-case> + <from-outcome>view</from-outcome> + <to-view-id>#{sessionScope['javax.portlet.faces.viewIdH= istory.view']}</to-view-id> + </navigation-case> + </navigation-rule> + + + Note to Portlet Developers + + Depending on the bridge implementation, when using values from these= session scoped attributes or any viewIds which may contain query string pa= rameters it may be necessary to use the wildcard syntax when identifying th= e rule target. For example, the above = + + +<to-view-id> + + + expression returns a viewId of the form = + +/viewId?javax.portlet.faces.PortletMode=3Dview&.... + + + Without wildcarding, when a subsequent navigation occurs from this n= ew view, the navigation rules wouldn't resolve because there wouldn't be an= exact match. Likewise, the above edit.jspx = + +<from-view-id> + + + is wildcarded because there are navigation rules that target it that= use a query string: + +<to-view-id> /edit.jspx?javax.portlet.faces.PortletM= ode=3Dedit </to-view-id> + + + Developers are encouraged to use such wildcarding to ensure they exec= ute properly in the broadest set of bridge implementations. + + +
+ +
+ Clearing The View History When Changing Portlet Modes + + By default the bridge remembers the view history when you switch to a d= ifferent portlet mode (like "Help" or "Edit"). You + can use the following parameter in your portlet.xml to use the de= fault viewId each time you switch modes. + + + + javax.portlet.faces.extension.resetModeViewId + true + + ]]> +
+ = +
+ General Error Handling + + + If you're developing a Seam portlet you can now use pages.xml for all = error handling. + + + + The following configuration may be used to handle exceptions. This is a= lso useful for handling session timeout and ViewExpiredExceptions. + + + Pay attention to the location element. It must contain the /faces/ mapp= ing to work properly. + + = + + <error-page> + <exception-type>javax.servlet.ServletException</excep= tion-type> + <location>/faces/error.xhtml</location> + </error-page> + <error-page> + <exception-type>javax.faces.application.ViewExpiredExcep= tion</exception-type> + <location>/faces/error.xhtml</location> + </error-page> + +
+ = +
+ Custom Ajax Error Handling + + By default, error handling is sent to a standard servlet page for Ajax = requests. To handle the error inside the portlet, use the following javascr= ipt: + + = + + <script type=3D"text/javascript"> + A4J.AJAX.onError =3D function(req,status,message){ + window.alert("Custom onError handler "+message); + } + + A4J.AJAX.onExpired =3D function(loc,expiredMsg){ + if(window.confirm("Custom onExpired handler "+expiredMsg+" fo= r a location: "+loc)){ + return loc; + } else { + return false; + } + } + </script> + + + Also, add the following to web.xml. Read more about these settings here= Reque= st Errors and Session Expiration Handling + + = + + <context-param> + <param-name>org.ajax4jsf.handleViewExpiredOnClient</param= -name> + <param-value>true</param-value> + </context-param> + +
+ = +
+ Communication Between Your Portlets + + There are roughly 4 different ways to send messages, events, and parame= ters between portlets which are contained in different ears/wars or contain= ed in the same war. The Portlet Container does not care if you have 2 portl= ets in the same war or if they are separated, because each portlet has a di= fferent HttpSession. + + + Of course, with the Portlet 2.0 spec, the recommended way to share a pa= rameter or event payload between 2 or more portlets are the and mecha= nisms. This allows you to decouple your application from surgically managin= g objects in the PortletSession.APPLICATION_SCOPE. + + + But, if these do not meet your usecase or you have a different strategy= , you can use one of the following methods. + +
+ @PortletScope(PortletScope.ScopeType.APPLICATION_SCOPE) + + + Then you would pull the statefull object from the session: + + = + + YourSessionClass yourSessionClass =3D (YourSessionClass)getRende= rRequest().getAttribute("javax.portlet.p./default/seamproject/seamprojectPo= rtletWindow?textHolder"); + + + This method is demonstrated in this video: Lesson 2: Portlet 1.0 Advanced Seam and RichFaces + +
+ = +
+ Using the PortletSession + + If you need to access the PortletSession to simply share a parameter/v= alue across multiple portlets, you can use the following to do so. + + = + + Object objSession =3D FacesContext.getCurrentInstance().getExternalC= ontext().getSession(false); + try + { + if (objSession instanceof PortletSession) + { + PortletSession portalSession =3D (PortletSession)objSession; + portalSession.setAttribute("your parameter name","parameter va= lue",PortletSession.APPLICATION_SCOPE); + ... + + + Then, in your JSP or Facelets page, you can use: + + = + + #{httpSessionScope['your parameter name']} + + + + Note to Portlet Developers + + #{httpSessionScope} was implemented after 2.0.0.BETA. If you are usi= ng the 1.0 bridge or pre 2.0.0.BETA, you must use the el variable #{session= ApplicationScope} + + + For more information about which EL variables are provided by the bri= dge, read section 6.5.1 of the JSR-329 specification. + +
+ +
+ = +
+ Linking to Portlet/JSF Pages Using h:outputink + + For linking to any JSF/Facelets page within your portlet web applicatio= n, you may use the following. + + = + + <h:outputLink value=3D"#{facesContext.externalContext.requestCont= extPath}/home.xhtml"> + <f:param name=3D"javax.portlet.faces.ViewLink" value=3D"true"/&= gt; + navigate to the test page + </h:outputLink> + +
+ +
+ Redirecting to an External Page or Resource + + To link to a non JSF view (i.e. jboss.org) you can use the following pa= rameter. + + + + <h:commandLink actionListener=3D"#{yourBean.yourListenr}"> + <f:param name=3D"javax.portlet.faces.DirectLink" value=3D"true"= /> + navigate to the test page + </h:commandLink> + + + Then in your backing bean, you must call a redirect(). + + +
+ +
+ Using Provided EL Variables + + All EL variables found in the JSR-329 (Portlet 2.0) specification are a= vailable in the JBoss Portlet Bridge. For + example, you can use the following to edit the portlet preference= s on the UI. + + + + + + +]]> + + Then in your backing bean, you must call the PortletPreferences.store()= method. + + +
+ + + + + + + + = + + +
+ Added: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Ref= erence_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml = (rev 0) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2010-04-28 15:= 59:53 UTC (rev 2880) @@ -0,0 +1,13 @@ + + +%BOOK_ENTITIES; +]> +
+ Building JSF Portlets + + + + +
+ Modified: portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_= Reference_Guide/en-US/modules/PortletDevelopment.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment.xml 2010-04-28 15:51:00 UTC (rev= 2879) +++ portal/branches/EPP_5_0_0_Branch_Docs/Enterprise_Portal_Platform_Refere= nce_Guide/en-US/modules/PortletDevelopment.xml 2010-04-28 15:59:53 UTC (rev= 2880) @@ -7,6 +7,6 @@ Portlet development = - + = --===============8285091940300783961==--