From portal-commits at lists.jboss.org Wed Jul 9 02:24:43 2008 Content-Type: multipart/mixed; boundary="===============2641034271531611623==" MIME-Version: 1.0 From: portal-commits at lists.jboss.org To: portal-commits at lists.jboss.org Subject: [portal-commits] JBoss Portal SVN: r11361 - docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules. Date: Wed, 09 Jul 2008 02:24:42 -0400 Message-ID: --===============2641034271531611623== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: thomas.heute(a)jboss.com Date: 2008-07-09 02:24:42 -0400 (Wed, 09 Jul 2008) New Revision: 11361 Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutorial= s.xml Log: Just started Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/t= utorials.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 --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutoria= ls.xml 2008-07-09 06:22:14 UTC (rev 11360) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/tutoria= ls.xml 2008-07-09 06:24:42 UTC (rev 11361) @@ -1,10 +1,9 @@ + + - Roy - Russo - - Chris Laprun @@ -15,470 +14,594 @@ Portlet Primer - JSR-168 Overview - The J= SR-168 Portlet Specification aims at defining portlets that can be = used by any JSR-168 portlet container, also known as a portal. There are di= fferent portals with commercial and non-commercial licenses. This chapter g= ives a brief overview of the JSR-168 Portlet Specification. Portlet develop= ers are strongly encouraged to read the JSR-168 Portlet Specification. + JSR-168 and JSR-286 overview + + The Portlet Specifications aims at defining portlets that can be = used by any + + JSR-168 (Portlet 1.0) + + or + + JSR-286 (Portlet 2.0) + + portlet container. Most Java EE portals include a portlet contain= er, it is + obvously the case for JBoss Portal which includes the JBoss Portl= et container + supporting the two versions. This chapter gives a brief overview = of the Portlet + Specifications. Portlet developers are strongly encouraged to rea= d the + + JSR-286 Portlet Specification + + . - JBoss Portal is fully JSR-168 compliant, which means any JSR-168 po= rtlet behaves as it should inside the portal. + JBoss Portal is fully JSR-286 compliant, which means any JSR-168 = or JSR-286 + portlet behaves as it is mandated by the respective specification= s inside the + portal. Portal Pages - A portal can be seen as pages with different areas, and inside areas, d= ifferent windows, and each window - having one portlet: - - - - - - - - + A portal can be seen as pages with different areas, and inside= areas, + different windows, and each window having one portlet: + + + + + + + + Rendering Modes - A portlet can have different view modes. Three modes are defined b= y the JSR-168 specification, but a portal can - extend those modes. The three modes are: - - + + A portlet can have different view modes. Three modes are defin= ed by the + JSR-288 specification: + + - - view - generates markup reflect= ing the current state of the portlet. - - + + view + - generates markup reflecting the current state of th= e portlet. + + - - edit - allows a user to customi= ze the behavior of the portlet. - - + + edit + - allows a user to customize the behavior of the port= let. + + - - help - provides information to = the user as to how to use the portlet. - - + + help + - provides information to the user as to how to use t= he portlet. + + Window States - Window states are an indicator of how much page real-estate a = portlet consumes on any given page. - The three states defined by the JSR-168 specification are: + Window states are an indicator of how much page real-estate a = portlet consumes + on any given page. The three states defined by the JSR-168 spe= cification are: - + - - normal - a portlet shares this = page with other portlets. - - + + normal + - a portlet shares this page with other portlets. + + - - minimized -a portlet may show v= ery little information, or none at all. - - + + minimized + -a portlet may show very little information, or none = at all. + + - - maximized - a portlet may be th= e only portlet displayed on this page. - - + + maximized + - a portlet may be the only portlet displayed on this= page. + + Section Status - - This overview of the JSR-168 Portlet Specification is a work in progres= s. Check back for more in-depth analsis of the specification. The sections = following here after contain real-world cases for how to leverage the speci= fication. - + + This overview of the JSR-168 Portlet Specification is a work i= n progress. + Check back for more in-depth analsis of the specification. The= sections + following here after contain real-world cases for how to lever= age the + specification. + Tutorials - The tutorials contained in this chapter are targetted toward port= let developers. Although they are a good - starting and reference point, it is highly recommend that portlet= developers read and understand the - JSR-168 Portlet= Specification. Use the JBoss Portal User Forums= for user-to-user help. + The tutorials contained in this chapter are targetted toward port= let developers. + Although they are a good starting and reference point, it is high= ly recommend + that portlet developers read and understand the + + JSR-286 Portlet Specification + + . Use the + + JBoss Portal User Forums + + for user-to-user help. - - Deploying your first Portlet Introduction - This section describes how to deploy a portlet in JBoss Portal. Befo= re proceeding, download the HelloWorldPortlet from JBoss PortletSwap. - + This section describes how to deploy a portlet in JBoss Por= tal. Before + proceeding, download the + + HelloWorldPortlet + + from + JBoss Por= tletSwap + . + Package Structure - Like other Java Platform, Enterprise Edition (Java EE) applications,= portlets are packaged in WAR files. A typical portlet WAR file can include= servlets, resource bundles, images, HTML, JavaS= erver Pages (JSP), and o= ther static or dynamic files. The following is an example of the directory = structure of the HelloWorldPortlet portlet: + Like other Java Platform, Enterprise Edition (Java EE) appl= ications, + portlets are packaged in WAR files. A typical portlet WAR f= ile can include + servlets, resource bundles, images, HTML, + JavaServer + Pages ( + JSP + ), and other static or dynamic files. The following is an e= xample of the + directory structure of the HelloWorldPortlet portlet: - - - - - - - - + + + + + + + + + + + + + + The compiled Java class implementing = javax.portlet.Portlet (through javax.portlet.GenericPo= rtlet) + + + + + default-object.xml is an o= ptional file, it is used to define the layout of the portal. It can be used= to define the different portals, pages and windows. + The same result can be obtained through the adm= inistration portal. Note that the definition of the layout is stored in dat= abase, this file is then used to populate the database + during deployment which can be very useful duri= ng development. + + + + + portlet-instances.xml is a= lso optional, it allows to create a portlet instance from the SimpleHelloWo= rld portlet definition. Creating + instances can also be done through the administ= ration portal. Note that the definition of instances is stored in database,= this file is then used to populate the database + during deployment which can be very useful duri= ng development. + + + + This is the mandatory descriptor files for p= ortlets. It is used during deployment.. + + + This is the mandatory descriptor for web app= lications. + + + + Portlet Classes - The following is the HelloWorldPortlet/src/main/org/jboss/= portlet/hello/HelloWorldPortlet.java Java source file, which com= es bundled with the HelloWorldPortlet: - - - + SimplestHelloWorldPortlet/src/main/java/org/jboss/portal= /portlet/samples/SimplestHelloWorldPortlet.java + + Java source file, which comes bundled with your JBoss Porta= l download: + + + + + + + + + + - - - - - -public class HelloWorldPortlet extends GenericPortlet - - - All portlets must implement the javax.por= tlet.Portlet interface. The portlet - API provides a convenient implementation of this i= nterface, in the form of the - javax.portlet.GenericPortlet cl= ass, which among other things, implements - the Portlet render method to di= spatch to abstract mode-specific methods to - make it easier to support the standard portlet mod= es. As well, it provides - a default implementation for the processA= ction, init and - destroy methods. It is recommen= ded to extend GenericPortlet - for most cases. - - - - -protected void doView(RenderRequest rRequest, RenderResponse rResponse) = -throws PortletException, IOException, UnavailableException - - - As we extend from GenericPortlet, and are only int= erested in supporting the view mode, only the d= oView method needs to be implemented, and the GenericPor= tlet render implemention calls our implementat= ion when the view mode is requested. - - - - -rResponse.setContentType("text/html"); - - - As in the servlet world, you must declare what content-type the portl= et will be - responding in. Do this before starting to write content, or the portl= et will throw an exception. - - - - -PrintWriter writer =3D rResponse.getWriter(); = -writer.write("Hello World!"); = -writer.close(); - - - This produces the Hello World! text in our portlet= window. - - - - - - - - Markup Fragments - - Portlets are responsible for generating markup fragments, as they are i= ncluded on a page and are - surrounded by other portlets. In particular, this means that a portlet = outputting HTML must - not output any markup that cannot be found in a <body> element. - - - + public void doView(RenderRequest request, = + RenderResponse response) throws IOException + { + PrintWriter writer =3D response.getWriter(); + writer.write("Hello World !"); + writer.close(); + } +}]]> + + + + + All portlets must implement the + javax.portlet.Portlet + interface. The portlet API provides a convenien= t implementation + of this interface, in the form of the + javax.portlet.GenericPortlet + class, which among other things, implements the + Portlet render + method to dispatch to abstract mode-specific me= thods to make it + easier to support the standard portlet modes. A= s well, it + provides a default implementation for the + processAction + , + init + and + destroy + methods. It is recommended to extend + GenericPortlet + for most cases. + + + + + As we extend from + GenericPortlet + , and are only interested in supporting the + view + mode, only the + doView + method needs to be implemented, and the + GenericPortlet + render + implemention calls our implementation when the + view + mode is requested. + + + + + Use the + RenderResponse + to obtain a writer to be used to produce conten= t. + + + + Write the markup to display. + + + Closing the writer. + + + + + + Markup Fragments + + Portlets are responsible for generating markup fragme= nts, as they are + included on a page and are surrounded by other portle= ts. In + particular, this means that a portlet outputting HTML= must not output + any markup that cannot be found in a + <body> + element. + + + Application Descriptors - JBoss Portal requires certain descriptors to be included in= a portlet WAR file. Some of - these descriptors are defined by the JSR-168 Portlet Specification= , and others are specific to JBoss Portal. The following is an example of t= he directory structure of the HelloWorldPortlet portlet: - - - - - - - - - - To create the WEB-INF/ and META-INF/<= /filename> directories, extract the helloworldportlet.war file. - - - The following is an example of the HelloWorldPortlet/WEB-I= NF/portlet.xml file. This file must adhere to its definition in = the JSR-168 Portlet Specification. You may define more than one portlet app= lication in this file: - - - - + JBoss Portal requires certain descriptors to be included in= a portlet WAR + file. Some of these descriptors are defined by the Portlet + Specification, and others are specific to JBoss Portal. + + + The following is an example of the + SimplestHelloWorldPortlet/WEB-INF/portlet.xml + file. This file must adhere to its definition in the JSR-28= 6 Portlet + Specification. You may define more than one portlet applica= tion in this + file: + + + + + + + + + - HelloWorldPortlet - org.jboss.portlet.hello.HelloWorldPortlet + SimplestHelloWorldPortlet + + org.jboss.portal.portlet.samples.SimplestHelloWorldPortlet + - text/html - view + text/html - HelloWorld Portlet + Simplest Hello World Portlet ]]> - - - - - HelloWorldPortlet]]> - - - Define the portlet name. It does not have to be the class name. - - - -org.jboss.portlet.hello.HelloWorldPortlet]]= > - - - The Fully Qualified Name (FQN) of your portlet class must be declared he= re. - - - - - text/html - view -]]> - - - The <supports> element declares a= ll of the markup types that a portlet supports in the render method. This is accomplished via the - <mime-type> element, which is req= uired for every portlet. The declared MIME types must match the capability = of the portlet. As well, it allows you to pair which modes and window state= s are supported for each markup type. All portlets must support the view portlet mode, so this does not have to be de= clared. Use the <mime-type> element = to define which markup type your portlet supports, which in this example, i= s text/html. This section tells the portal= that it only outputs text and HTML, and that it only supports the view mode. - - - - - HelloWorld Portlet -]]> - - - When rendered, the portlet's title is displayed as the header in the por= tlet window, unless it is overridden programmatically. In this example, the= title would be HelloWorld Portlet. - - - - - - - The HelloWorldPortlet/WEB-INF/portlet-instances.xml= file is a JBoss Portal specific descriptor, that allows you to create inst= ances of portlets. The - <portlet-ref> value must match th= e <portlet-name> value - given in the HelloWorldPortlet/WEB-INF/portlet.xml = file. The <instance-id> - value can be named anything, but it must match the <i= nstance-ref> value given - in the *-object.xml file, which in this example, wo= uld be the HelloWorldPortlet/WEB-INF/helloworld-object.xml file. - - - The following is an example of the HelloWorldPortlet/WEB-INF/po= rtlet-instances.xml file: - - - + + + + Define the portlet name. It does not have to be th= e class name. + + + + The Fully Qualified Name (FQN) of your portlet = class must be + declared here. + + + + + The + <supports> + element declares all of the markup types that a= portlet + supports in the + render + method. This is accomplished via the + <mime-type> + element, which is required for every portlet. T= he declared MIME + types must match the capability of the portlet.= As well, it + allows you to pair which modes and window state= s are supported + for each markup type. All portlets must support= the + view + portlet mode, so this does not have to be decla= red. Use the + <mime-type> + element to define which markup type your portle= t supports, + which in this example, is + text/html + . This section tells the portal that it only ou= tputs HTML. + + + + + When rendered, the portlet's title is displayed= as the header + in the portlet window, unless it is overridden + programmatically. In this example, the title wo= uld be + HelloWorld Portlet + . + + + + + + The + HelloWorldPortlet/WEB-INF/portlet-instances.xml + file is a JBoss Portal specific descriptor, that allows you= to create + instances of portlets. The + <portlet-ref> + value must match the + <portlet-name> + value given in the + HelloWorldPortlet/WEB-INF/portlet.xml + file. The + <instance-id> + value can be named anything, but it must match the + <instance-ref> + value given in the + *-object.xml + file, which in this example, would be the + SimplestHelloWorldPortlet/WEB-INF/default-object.= xml + file. + + + The following is an example of the + SimplestHelloWorldPortlet/WEB-INF/portlet-instanc= es.xml + file: + + + "http://www.jboss.org/portlet/dtd/portlet-instances_2_6.dtd"> - HelloWorldPortletInstance - HelloWorldPortlet + SimplestHelloWorldInstance + SimplestHelloWorldPortlet ]]> - - - - The *-object.xml file is a JBoss Portal specific des= criptor that allow users to - define the structure of their portal instances, and create and configure = their windows and - pages. In the following example: - - - - - - a portlet window is created. - - - - - specifies that the window displays the markup generated by the HelloWorldPortletInstance portlet instance. - - - - - the window is assigned to the default.default page. - - - - - the <region> element specifies = where the window appears on the page. - - - - - - The following is an example HelloWorldPortlet/WEB-INF/helloworl= d-object.xml file: - - - + + + The + *-object.xml + file is a JBoss Portal specific descriptor that allow users= to define the + structure of their portal instances, and create and configu= re their windows + and pages. In the following example: + + + + + a portlet window is created. + + + + specifies that the window displays the markup gene= rated by the + HelloWorldPortletInstance + portlet instance. + + + + + the window is assigned to the + default.default + page. + + + + + the + <region> + element specifies where the window appears on the = page. + + + + + + The following is an example + SimplestHelloWorldPortlet/WEB-INF/default-object.= xml + file: + + + + + + + + + + + - default.default + default overwrite - - HelloWorldPortletWindow - HelloWorldPortletInstance - center - 1 - + + SimplestHelloWorld + + SimplestHelloWorldWindow + SimplestHelloWorldInstance + center + 0 + + ]]> - - - - - - default.default]]> - - - - Tells the portal where this portlet appears. In this case, default.default specifies that the portlet appears in t= he portal instance named default, and on t= he page named default. - - - -overwrite]]> - - - - Instructs the portal to overwrite or keep this object if it already exis= ts. Accepted values are overwrite and keep. The overwrite option destroys the existing object, and creates a new one based on = the content of the deployment. The keep op= tion maintains the existing object deployment, or creates a new one if it d= oes not exist. - - - -HelloWorldPortletWindow]]> - - - - A unique name given to the portlet wi= ndow. This can be named anything. - - - -HelloWorldPortletInstance]]> - - - - The value of <instance-ref> must = match the value of one of the - <instance-id> elements found in t= he HelloWorldPortlet/WEB-INF/portlet-instances.xml fi= le. - - - -center -1]]> - - - - Specifies where the window appears within the page layout. - - - - - - - The following diagram illustrates the relationship between the = portlet.xml, portlet-instances.xml, and helloworld-object.xml descriptors: - - + + + + + Tells the portal where this portlet appears. In= this case, + default.default + specifies that the portlet appears in the porta= l instance named + default + , and on the page named + default + . + + + + + Instructs the portal to overwrite or keep this = object if it + already exists. Accepted values are + overwrite + and + keep + . The + overwrite + option destroys the existing object, and create= s a new one + based on the content of the deployment. The + keep + option maintains the existing object deployment= , or creates a + new one if it does not exist. + + + + + A + unique name + given to the portlet window. This can be named = anything. + + + + + The value of + <instance-ref> + must match the value of one of the + <instance-id> + elements found in the + + HelloWorldPortlet/WEB-INF/portlet-instances.= xml + + file. + + + + + Specifies where the window appears within the p= age layout. + + + + + Specifies where the window appears within the p= age layout. + + + + + + The following diagram illustrates the relationship between = the + portlet.xml + , + portlet-instances.xml + , and + helloworld-object.xml + descriptors: + + - + - + = - JBoss Portal 2.6 introduces the notion of content= -type, which is a generic mechanism to - specify what content displayed by a given portlet window. T= he window section - of the previous example, HelloWorldPortlet/WEB-INF/hello= world-object.xml, can be re-written to take advantage of the new= content framework. The following is an example deployment descriptor that = uses the new content framework: + JBoss Portal 2.6 introduced the notion of + content-type + , which is a generic mechanism to specify what content disp= layed by a given + portlet window. The + window + section of the previous example, + SimplestHelloWorldPortlet/WEB-INF/default-object.= xml + , can be re-written to take advantage of the new content fr= amework. The + following is an example deployment descriptor that uses the= new content + framework: - - default.default overwrite - HelloWorldPortletWindow + SimplestHelloWorldWindow portlet - HelloWorldPortletInstance + SimplestHelloWorldInstance center 1 ]]> - - - + + = - This declaration is equivalent to the previous HelloWorldPortl= et/WEB-INF/helloworld-object.xml example. Use &l= t;content-type> to specify the content to display. In t= his example, the content being displayed by the HelloWorldP= ortletWindow is a portlet= . The <content-uri> element specifie= s which content to display, which in this example, is the H= elloWorldPortletInstance: - - - + This declaration is equivalent to the previous + SimplestHelloWorldPortlet/WEB-INF/default-object.= xml + example. Use + <content-type> + to specify the content to display. In this example, the con= tent being + displayed by the + SimplestHelloWorldWindow + is a + portlet + . The + <content-uri> + element specifies which content to display, which in this e= xample, is the + HelloWorldPortletInstance + : + + portlet HelloWorldPortletInstance ]]> - - - - To display certain content or a file, use the cms content-type, with the <content-uri> element being the path to the file in the CMS. This behavior is= pluggable: you can plug in almost any type of content. - = + + + To display certain content or a file, use the + cms + content-type, with the + <content-uri> + element being the path to the file in the CMS. This behavio= r is pluggable: + you can plug in almost any type of content. + Building your Portlet - The HelloWorldPortlet.zip file contains a pre-c= ompiled helloworldportlet.war file; however, to manual= ly build the helloworldportlet.war file: - - - - - - Change into the HelloWorldPortlet/ directory= , and remove the existing helloworldportlet.war file. - - - - - If required, edit the HelloWorldPortlet/src/main/org/jb= oss/portlet/hello/HelloWorldPortlet.java file, and the applicati= on descriptors in the HelloWorldPortlet/src/resources/helloworldp= ortlet-war/WEB-INF/ directory. - - - - - Change into HelloWorldPortlet/ directory, an= d run the ant deploy command. On Windows, the output wil= l be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - + The + HelloWorldPortlet.zip + file contains a pre-compiled + helloworldportlet.war + file; however, to manually build the + helloworldportlet.war + file: + - Expanding the helloworldportlet.war file allows= you to deploy the portlet as an expanded directory, which makes developmen= t easier. As well, it gives you access to the application descriptors, reso= urce files, JSF, and JSP pages. To expand the helloworldportlet.w= ar file: - - - - - - If you do not have the HelloWorldPortlet/helloworldport= let.war file, change into the HelloWorldPortlet/ directory, and run the ant deploy command. This cr= eates the helloworldportlet.war file. - - - - - To expand the WAR file, change into the HelloWorldPortl= et/ directory, and run the ant explode comman= d. On Windows, the output will be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - - - The ant explode command creates a directory struc= ture such as the following: - - + + + + Change into the + HelloWorldPortlet/ + directory, and remove the existing + helloworldportlet.war + file. + + + + + If required, edit the + + HelloWorldPortlet/src/main/org/jboss/portlet/he= llo/HelloWorldPortlet.java + + file, and the application descriptors in the + + HelloWorldPortlet/src/resources/helloworldportl= et-war/WEB-INF/ + + directory. + + + + + Change into + HelloWorldPortlet/ + directory, and run the + ant deploy + command. On Windows, the output will be similar to= the following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + Expanding the + helloworldportlet.war + file allows you to deploy the portlet as an expanded direct= ory, which makes + development easier. As well, it gives you access to the app= lication + descriptors, resource files, JSF, and JSP pages. To expand = the + helloworldportlet.war + file: + + + + + + If you do not have the + HelloWorldPortlet/helloworldportlet.war<= /filename> + file, change into the + HelloWorldPortlet/ + directory, and run the + ant deploy + command. This creates the + helloworldportlet.war + file. + + + + + To expand the WAR file, change into the + HelloWorldPortlet/ + directory, and run the + ant explode + command. On Windows, the output will be similar to= the following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + The + ant explode + command creates a directory structure such as the following: + + - + - - - The expanded WAR file and the application descriptors are located i= n the HelloWorldPortlet/output/lib/exploded/helloworldportlet.war= /WEB-INF/ directory. + + The expanded WAR file and the application descriptors are l= ocated in the + + HelloWorldPortlet/output/lib/exploded/helloworldportlet.= war/WEB-INF/ + + directory. + Deploying your Portlet - If you did not expand the helloworldportlet.war f= ile, copy the HelloWorldPortlet/helloworldportlet.war = file into the correct JBoss AS or JBoss EAP deploy/ di= rectory. If you expanded the helloworldportlet.war fil= e, copy the HelloWorldPortlet/output/lib/exploded/helloworldportl= et.war/ directory into the correct JBoss AS or JBoss EAP deploy/ directory. For example, if you are using the default JBoss AS profile, copy the WAR file or the= expanded directory into the $JBOSS_HOME/server/default/deploy/ directory. - - - Performing this step on a running instance of JBoss AS or JBoss EAP,= and JBoss Portal, triggers a hot-deploy of the portlet: - - -helloworldportlet.war + file, copy the + HelloWorldPortlet/helloworldportlet.war + file into the correct JBoss AS or JBoss EAP + deploy/ + directory. If you expanded the + helloworldportlet.war + file, copy the + + HelloWorldPortlet/output/lib/exploded/helloworldportlet.= war/ + + directory into the correct JBoss AS or JBoss EAP + deploy/ + directory. For example, if you are using the + default + JBoss AS profile, copy the WAR file or the expanded directo= ry into the + $JBOSS_HOME/server/default/deploy/ + directory. + + + Performing this step on a running instance of JBoss AS or J= Boss EAP, and + JBoss Portal, triggers a hot-deploy of the portlet: + + + - - - - To see the HelloWorldPortlet, navigate to http://localhost:8080/portal/, or, if the default= JBoss Portal page is already open, refresh the page. The HelloWorldPortlet= is added to the bottom of the default JBoss Portal page: - - + + + + To see the HelloWorldPortlet, navigate to + + http://localhost:8080/portal/ + + , or, if the default JBoss Portal page is already open, ref= resh the page. + The HelloWorldPortlet is added to the bottom of the default= JBoss Portal + page: + + - + - - To re-deploy the portlet, for example, if you have made changes to a= ny of the application descriptors, touch the $JBOSS_HOME/server/<= replaceable>configuration/deploy/helloworldportlet.war/WEB-IN= F/web.xml file. This only works if you copied the Hell= oWorldPortlet/output/lib/exploded/helloworldportlet.war/ directo= ry into the JBoss AS or JBoss EAP deploy/ directory. O= n Linux, run the following command to re-deploy the HelloWorldPortlet: - - - -touch $JBOSS_HOME/server/configuration/deploy/h= elloworldportlet.war/WEB-INF/web.xml - - - - Re-deploying the HelloWorldPortlet produces output to the JBoss AS or= JBoss EAP console, similar to the following: - - - + To re-deploy the portlet, for example, if you have made cha= nges to any of + the application descriptors, touch the + + $JBOSS_HOME/server/ + configuration + /deploy/helloworldportlet.war/WEB-INF/web.xml + + file. This only works if you copied the + + HelloWorldPortlet/output/lib/exploded/helloworldportlet.= war/ + + directory into the JBoss AS or JBoss EAP + deploy/ + directory. On Linux, run the following command to re-deploy= the + HelloWorldPortlet: + + + + touch $JBOSS_HOME/server/ + configuration + /deploy/helloworldportlet.war/WEB-INF/web.xml + + + + Re-deploying the HelloWorldPortlet produces output to the J= Boss AS or JBoss + EAP console, similar to the following: + + + - - - + + + - An example <trademark class=3D"trade">JavaServer</trademar= k> Pages (<trademark class=3D"trade">JSP</trademark>) portlet + + An example + <trademark class=3D"trade">JavaServer</trademark> + Pages ( + <trademark class=3D"trade">JSP</trademark> + ) portlet + Introduction - - This section describes how to deploy a JS= P portlet in JBoss Portal. Before proceeding, download the HelloWorldJSPPortlet from JBoss PortletSwap. The HelloWorld= JSPPortlet demonstrates how to use JSP pages for view rendering, and the po= rtlet tag library (taglib) for generating links. + + This section describes how to deploy a + JSP + portlet in JBoss Portal. Before proceeding, download the + + HelloWorldJSPPortlet + + from + JBoss Por= tletSwap + . The HelloWorldJSPPortlet demonstrates how to use JSP page= s for view + rendering, and the portlet tag library (taglib) for generat= ing links. Package Structure - The application descriptors for the HelloWorldJSPPortlet portlet are= similar to those from the HelloWorldPortlet (). Refer to for fur= ther information about application descriptors. - - - The HelloWorldJSPPortlet portlet contains the traditional portlet an= d JBoss Portal specific application descriptors. The following is an exampl= e of the directory structure of the HelloWorldJSPPortlet portlet: - - + The application descriptors for the HelloWorldJSPPortlet po= rtlet are + similar to those from the HelloWorldPortlet ( + + ). Refer to + + for further information about application descriptors. + + + The HelloWorldJSPPortlet portlet contains the traditional p= ortlet and JBoss + Portal specific application descriptors. The following is a= n example of the + directory structure of the HelloWorldJSPPortlet portlet: + + - + - - To create the WEB-INF/ and META-INF/<= /filename> directories, extract the helloworldjspportlet.war file. - + + To create the + WEB-INF/ + and + META-INF/ + directories, extract the + helloworldjspportlet.war + file. + Portlet Classes - The HelloWorldJSPPortlet contai= ns the HelloWorldJSPPortlet/src/main/org/jboss/portlet/hello/Hell= oWorldJSPPortlet.java file: - - - + HelloWorldJSPPortlet + + contains the + + HelloWorldJSPPortlet/src/main/org/jboss/portlet/hello/He= lloWorldJSPPortlet.java + + file: + + + - - - - - + + + + + + - + - - - - Support for these modes must be declared in the HelloWorldJSPP= ortlet/WEB-INF/portlet.xml file. They are triggered when a user = clicks on the respective icons in the portlet window titlebar, or through g= enerated links within the portlet. - - - - + + + + Support for these modes must be declared in the + HelloWorldJSPPortlet/WEB-INF/portlet.= xml + file. They are triggered when a user clicks on = the respective + icons in the portlet window titlebar, or throug= h generated + links within the portlet. + + + + + + - - - - This method is triggered when a user clicks on an action= URL, which is defined in the HelloWorldJSPPortle= t/WEB-INF/jsp/view.jsp file. This retrieves your= name from the HTML form, and passes it as a aResponse.setRenderParameter to the doView() method. - - - - + + + + This method is triggered when a user clicks on = an + actionURL + , which is defined in the + HelloWorldJSPPortlet/WEB-INF/jsp/view= .jsp + file. This retrieves + yourname + from the HTML form, and passes it as a + aResponse.setRenderParameter + to the + doView() + method. + + + + + + - - - - As in the servlet world, you must declare what content-type the portlet = will be responding in. Do this before starting to write content, or the por= tlet throws an exception. - - - - + + + + As in the servlet world, you must declare what = content-type the + portlet will be responding in. Do this before s= tarting to write + content, or the portlet throws an exception. + + + + + + - - - - The doView implementation is responsible for dispatch= ing to the appropriate JSP, HelloWorldJSPPortlet/WEB-INF/jsp/view= .jsp or HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp, depending on the existence of the yourname para= meter passed in from processAction. - - - - - + + + + + The + doView + implementation is responsible for dispatching t= o the + appropriate JSP, + HelloWorldJSPPortlet/WEB-INF/jsp/view= .jsp + or + HelloWorldJSPPortlet/WEB-INF/jsp/view= 2.jsp + , depending on the existence of the + yourname + parameter passed in from + processAction + . + + + + + - <trademark class=3D"trade">JSP</trademark> files and th= e Portlet Tag Library + + <trademark class=3D"trade">JSP</trademark> + files and the Portlet Tag Library + - The HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp a= nd HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp JSP files are included in the HelloWorldJSPP= ortlet portlet. The view.jsp file allows a user to inp= ut their name. This is then posted to the processAction method in the portlet class, which is set as a aResponse.setRenderParameter. The doView= render method is invoked, which dispat= ches to the view2.jsp JSP: - - + The + HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp + and + HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp + JSP + files are included in the HelloWorldJSPPortlet portlet. The + view.jsp + file allows a user to input their name. This is then posted= to the + processAction + method in the portlet class, which is set as a + aResponse.setRenderParameter + . The + doView + render + method is invoked, which dispatches to the + view2.jsp + JSP: + + - + - - The following is an example of the HelloWorldJSPPortlet/WE= B-INF/jsp/view.jsp file: + + The following is an example of the + HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp + file: - = @@ -826,215 +1158,400 @@ href=3D" ">this. ]]> - - - - - + + + + + + ]]> - - - - Define the portlet taglib. You do not need to bundle the portlet taglib = - JBoss Portal handles this for you. - - - - + + + + Define the portlet taglib. You do not need to b= undle the + portlet taglib - JBoss Portal handles this for = you. + + + + + + ]]> - - - - Calling defineObjects makes available implicit object= s in the JSP, such as - renderRequest, actionRequest, and = portletConfig. - - - - + + + + Calling + defineObjects + makes available implicit objects in the JSP, su= ch as + renderRequest + , + actionRequest + , and + portletConfig + . + + + + + + " method=3D"POST">]]> - - - - A HTML form is created. This form posts to the URL defined by the portle= t taglib. In this example, an actionURL is= created, that activates the processAction method, which= passes the input parameters from the form. - - - - + + + + A HTML form is created. This form posts to the = URL defined by + the portlet taglib. In this example, an + actionURL + is created, that activates the + processAction + method, which passes the input parameters from = the form. + + + + + + ">]]> - - - - You can create a link to the doView met= hod by creating a renderURL, which passes = the yourname parameter. - - - - - + + + + + You can create a link to the + doView + method by creating a + renderURL + , which passes the + yourname + parameter. + + + + + - Building your <trademark class=3D"trade">JSP</trademark= > portlet - - The HelloWorldJSPPortlet.zip file contains a pr= e-compiled helloworldjspportlet.war file; however, to = manually build the helloworldjspportlet.war file: - - - - - - Change into the HelloWorldJSPPortlet/ direct= ory, and remove the existing helloworldjspportlet.war = file. - - - - - If required, edit the HelloWorldJSPPortlet/src/main/org= /jboss/portlet/hello/HelloWorldJSPPortlet.java file, and the app= lication descriptors in the HelloWorldJSPPortlet/src/resources/he= lloworldjspportlet-war/WEB-INF/ directory. - - - - - Change into HelloWorldJSPPortlet/ directory,= and run the ant deploy command. On Linux, the output wi= ll be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - = - - Expanding the helloworldjspportlet.war file all= ows you to deploy the portlet as an expanded directory, which makes develop= ment easier. As well, it gives you access to the application descriptors, r= esource files, JSF, and JSP pages. T= o expand the helloworldjspportlet.war file: - - - - - - If you do not have the HelloWorldJSPPortlet/helloworldj= spportlet.war file, change into the HelloWorldJSPPortl= et/ directory, and run the ant deploy command= . This creates the helloworldjspportlet.war file. - - - - - To expand the WAR file, change into the HelloWorldJSPPo= rtlet/ directory, and run the ant explode com= mand. On Linux, the output will be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - - - The ant explode command creates a directory struc= ture such as the following: - - - - - - - - - - The expanded WAR file and the application descriptors are located in= the HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportle= t.war/WEB-INF/ directory. - - - - Deploying your <trademark class=3D"trade">JSP</trademark> port= let - - If you did not expand the helloworldjspportlet.war file, copy the HelloWorldJSPPortlet/helloworldjspportlet.war<= /filename> file into the correct JBoss AS or JBoss EAP deploy/ directory. If you expanded the helloworldjspportlet.war<= /filename> file, copy the HelloWorldJSPPortlet/output/lib/explode= d/helloworldjspportlet.war/ directory into the correct JBoss AS = or JBoss EAP deploy/ directory. For example, if you ar= e using the default JBoss AS profile, copy= the WAR file or the expanded directory into the $JBOSS_HOME/serv= er/default/deploy/ directory. - - - Performing this step on a running instance of JBoss AS or JBoss EAP,= and JBoss Portal, triggers a hot-deploy of the portlet: - - - + Building your + JSP + portlet + + + The + HelloWorldJSPPortlet.zip + file contains a pre-compiled + helloworldjspportlet.war + file; however, to manually build the + helloworldjspportlet.war + file: + + + + + + Change into the + HelloWorldJSPPortlet/ + directory, and remove the existing + helloworldjspportlet.war + file. + + + + + If required, edit the + + HelloWorldJSPPortlet/src/main/org/jboss/portlet= /hello/HelloWorldJSPPortlet.java + + file, and the application descriptors in the + + HelloWorldJSPPortlet/src/resources/helloworldjs= pportlet-war/WEB-INF/ + + directory. + + + + + Change into + HelloWorldJSPPortlet/ + directory, and run the + ant deploy + command. On Linux, the output will be similar to t= he following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + Expanding the + helloworldjspportlet.war + file allows you to deploy the portlet as an expanded direct= ory, which makes + development easier. As well, it gives you access to the app= lication + descriptors, resource files, JSF, and + JSP + pages. To expand the + helloworldjspportlet.war + file: + + + + + + If you do not have the + HelloWorldJSPPortlet/helloworldjspportle= t.war + file, change into the + HelloWorldJSPPortlet/ + directory, and run the + ant deploy + command. This creates the + helloworldjspportlet.war + file. + + + + + To expand the WAR file, change into the + HelloWorldJSPPortlet/ + directory, and run the + ant explode + command. On Linux, the output will be similar to t= he following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + The + ant explode + command creates a directory structure such as the following: + + + + + + + + + + The expanded WAR file and the application descriptors are l= ocated in the + + HelloWorldJSPPortlet/output/lib/exploded/helloworldjsppo= rtlet.war/WEB-INF/ + + directory. + + + + + Deploying your + <trademark class=3D"trade">JSP</trademark> + portlet + + + If you did not expand the + helloworldjspportlet.war + file, copy the + HelloWorldJSPPortlet/helloworldjspportlet.war + file into the correct JBoss AS or JBoss EAP + deploy/ + directory. If you expanded the + helloworldjspportlet.war + file, copy the + + HelloWorldJSPPortlet/output/lib/exploded/helloworldjsppo= rtlet.war/ + + directory into the correct JBoss AS or JBoss EAP + deploy/ + directory. For example, if you are using the + default + JBoss AS profile, copy the WAR file or the expanded directo= ry into the + $JBOSS_HOME/server/default/deploy/ + directory. + + + Performing this step on a running instance of JBoss AS or J= Boss EAP, and + JBoss Portal, triggers a hot-deploy of the portlet: + + + - - - - To see the HelloWorldJSPPortlet, navigate to , or, if the default JBoss Portal page is already = open, refresh the page. The HelloWorldJSPPortlet is added to the bottom of = the default JBoss Portal page: - - - - - - - - - - To re-deploy the portlet, for example, if you have made changes to any of= the application descriptors, touch the $JBOSS_HOME/server/configuration/deploy/helloworldjspportlet.war/WEB-INF/= web.xml file. This only works if you copied the HelloW= orldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/ dir= ectory into the JBoss AS or JBoss EAP deploy/ director= y. On Linux, run the following command to re-deploy the HelloWorldJSPPortle= t: - - - -touch $JBOSS_HOME/server/configuration/deploy/h= elloworldjspportlet.war/WEB-INF/web.xml - - - - Re-deploying the HelloWorldJSPPortlet produces output to the JBoss AS or = JBoss EAP console, similar to the following: - - - + + + To see the HelloWorldJSPPortlet, navigate to + + , or, if the default JBoss Portal page is already open, ref= resh the page. + The HelloWorldJSPPortlet is added to the bottom of the defa= ult JBoss Portal + page: + + + + + + + + + + To re-deploy the portlet, for example, if you have made cha= nges to any of + the application descriptors, touch the + + $JBOSS_HOME/server/ + configuration + /deploy/helloworldjspportlet.war/WEB-INF/web.xml + + file. This only works if you copied the + + HelloWorldJSPPortlet/output/lib/exploded/helloworldjsppo= rtlet.war/ + + directory into the JBoss AS or JBoss EAP + deploy/ + directory. On Linux, run the following command to re-deploy= the + HelloWorldJSPPortlet: + + + + touch $JBOSS_HOME/server/ + configuration + /deploy/helloworldjspportlet.war/WEB-INF/web.xml + + + + Re-deploying the HelloWorldJSPPortlet produces output to th= e JBoss AS or + JBoss EAP console, similar to the following: + + + - - - - + + + + - An example <trademark class=3D"trade">Sun</trademark> JSF = Reference Implementation (RI) portlet + + An example + <trademark class=3D"trade">Sun</trademark> + JSF Reference Implementation (RI) portlet + Introduction - This section describes how to deploy a JSF portlet in JBoss Portal, = using the Apache MyFaces JSF implementation in JBoss AS and JBoss EAP. Befo= re proceeding, download the HelloWorldJSF= SunRIPortlet from JBoss PortletSwap. + This section describes how to deploy a JSF portlet in JBoss= Portal, using + the Apache MyFaces JSF implementation in JBoss AS and JBoss= EAP. Before + proceeding, download the + + HelloWorldJSFSunRIPortlet + + from + JBoss Por= tletSwap + . - = + Package Structure - - JBoss Portal requires certain descriptors to be included in a portle= t WAR file. Some of these descriptors are defined by the JSR-168 Portlet Sp= ecification, and others are specific to JBoss Portal. Like a typical JSF ap= plication, the HelloWorldJSFSunRIPortlet package contains a faces= -config.xml file that defines managed-beans, converters, validat= ors, navigation rules, and so on. The following is an example of the direct= ory structure of the HelloWorldJSFSunRIPortlet portlet: - + JBoss Portal requires certain descriptors to be included in= a portlet WAR + file. Some of these descriptors are defined by the JSR-168 = Portlet + Specification, and others are specific to JBoss Portal. Lik= e a typical JSF + application, the HelloWorldJSFSunRIPortlet package contains= a + faces-config.xml + file that defines managed-beans, converters, validators, na= vigation rules, + and so on. The following is an example of the directory str= ucture of the + HelloWorldJSFSunRIPortlet portlet: + + - + - - - To create the WEB-INF/ and META-INF/= directories, extract the helloworldjsfsunriportlet.wa= r file. - - + + + To create the + WEB-INF/ + and + META-INF/ + directories, extract the + helloworldjsfsunriportlet.war + file. + + - Bundled <trademark class=3D"trade">Sun</trademark> JSF RI<= /title> - <para> - JBoss AS version 4.2.<replaceable>x</replaceable> and JBoss EAP = bundle the <trademark class=3D"trade">Sun</trademark> JSF RI libraries in t= he - <filename>$JBOSS_HOME/server/default/deploy/jboss-web.de= ployer/jsf-libs/</filename> directory. Therefore, you do not need to packag= e the Sun JSF RI libraries with your portlet application. - </para> + <title> + Bundled + <trademark class=3D"trade">Sun</trademark> + JSF RI + + + JBoss AS version 4.2. + x + and JBoss EAP bundle the + Sun + JSF RI libraries in the + + $JBOSS_HOME/server/default/deploy/jboss-web.deploy= er/jsf-libs/ + + directory. Therefore, you do not need to package the = Sun JSF RI + libraries with your portlet application. + - - - Application Descriptors + + + Application Descriptors - Only the portlet.xml, faces-config.xm= l, and web.xml descriptors are described he= re. For more information about application descriptors, refer to and . - - - The following is an example of the HelloWorldJSFSunRIPor= tlet/WEB-INF/portlet.xml file. This file must adhere to its defi= nition in the JSR-168 Portlet Specification. You may define more than one p= ortlet application in this file: - - -portlet.xml + , + faces-config.xml + , and + web.xml + descriptors are described here. For more information about = application + descriptors, refer to + + and + + . + + + The following is an example of the + HelloWorldJSFSunRIPortlet/WEB-INF/portlet.xml + file. This file must adhere to its definition in the JSR-16= 8 Portlet + Specification. You may define more than one portlet applica= tion in this + file: + + + ]]> - - - - - + + + + + + com.sun.faces.portlet.FacesPortlet]]> - - - - This specifies that the com.sun.faces.portlet.FacesPortl= et handles all requests and responses from the users. This= class is part of the HelloWorldJSFSunRIPortlet/WEB-INF/lib/jsf-p= ortlet.jar file. - - - - + + + + This specifies that the + + com.sun.faces.portlet.FacesPortlet + + handles all requests and responses from the use= rs. This class + is part of the + + HelloWorldJSFSunRIPortlet/WEB-INF/lib/jsf-po= rtlet.jar + + file. + + + + + + com.sun.faces.portlet.INIT_VIEW /WEB-INF/jsp/index.jsp ]]> - - - - You must initialize the portlet with a default page to render, similar t= o a welcome page. - - - - + + + + You must initialize the portlet with a default = page to render, + similar to a welcome page. + + + + + + text/html view -]]> - - - The <supports> element all= ows you to declare all of the markup types that a portlet supports in the <= literal>render method. This is accomplished via the - <mime-type> element, which= is required for every portlet. The declared MIME types must match the capa= bility of the portlet. As well, it allows you to pair which modes and windo= w states are supported for each markup type. All portlets must support the = view portlet mode, so this does not have t= o be declared. Use the <mime-type> e= lement to define which markup type your portlet supports, which in this exa= mple, is text/html. This section tells the= portal that it only outputs text and HTML, and that it only supports the <= computeroutput>view mode. - - - - - - - The following is an example HelloWorldJSFSunRIPortlet/WEB-INF/f= aces-config.xml file: - - -]]> + + + + The + <supports> + element allows you to declare all of the markup= types that a + portlet supports in the + render + method. This is accomplished via the + <mime-type> + element, which is required for every portlet. T= he declared MIME + types must match the capability of the portlet.= As well, it + allows you to pair which modes and window state= s are supported + for each markup type. All portlets must support= the + view + portlet mode, so this does not have to be decla= red. Use the + <mime-type> + element to define which markup type your portle= t supports, + which in this example, is + text/html + . This section tells the portal that it only ou= tputs text and + HTML, and that it only supports the + view + mode. + + + + + + + The following is an example + HelloWorldJSFSunRIPortlet/WEB-INF/faces-config.xm= l + file: + + + ]]> - - - - Without the faces-config.xml file, the application w= ould work the same outside of the portlet as it would inside a portlet cont= ainer. In this example, a basic user bean, <managed-bean= -name>user</managed-bean-name>, and a navigation = rule are defined, which handle the submission of the original form in the <= filename>HelloWorldJSFSunRIPortlet/WEB-INF/jsp/index.jsp file. - - - The following is an example of the Faces Servlet and Faces Servlet Mapping section= s from the HelloWorldJSFSunRIPortlet/WEB-INF/web.xml f= ile: - - - + + + Without the + faces-config.xml + file, the application would work the same outside of the po= rtlet as it + would inside a portlet container. In this example, a basic = user bean, + + <managed-bean-name>user</managed-bean-name> + + , and a navigation rule are defined, which handle the submi= ssion of the + original form in the + HelloWorldJSFSunRIPortlet/WEB-INF/jsp/index.jsp + file. + + + The following is an example of the + Faces Servlet + and + Faces Servlet Mapping + sections from the + HelloWorldJSFSunRIPortlet/WEB-INF/web.xml + file: + + + = ]]> - - - - For Sun JSF RI portlets, the Faces Servlet and Faces Servlet Mapping sections are = required to associate files with the .jsf extension to= the Apache MyFaces servlet. - - - - Classes for the JSF-Portlet bridge are not included - - Unlike Apache MyFaces, the classes for the JSF-Portlet bridge are not i= ncluded in the JSF implementation, JBoss AS, or JBoss EAP. This library mus= t be available in your application package. Navigate to the JSF-Port= let bridge webpage to download the JSF-Portlet bridge library. - - - + + + + For Sun JSF RI portlets, the + Faces Servlet + and + Faces Servlet Mapping + sections are required to associate files with the + .jsf + extension to the Apache MyFaces servlet. + + + + Classes for the JSF-Portlet bridge are not includ= ed + + Unlike Apache MyFaces, the classes for the JSF-Portle= t bridge are not + included in the JSF implementation, JBoss AS, or JBos= s EAP. This + library must be available in your application package= . Navigate to + the + + JSF-Portlet bridge webpage + + to download the JSF-Portlet bridge library. + + + - Building your JSF portlet - - The HelloWorldJSFSunRIPortlet.zip file contains a= pre-compiled helloworldjsfsunriportlet.war file; howe= ver, to manually build the helloworldjsfsunriportlet.war file: - - - - - - Change into the HelloWorldJSFSunRIPortlet/ dir= ectory, and remove the existing helloworldjsfsunriportlet.war file. - - - - - If required, edit the HelloWorldJSFSunRIPortlet/src/main/= org/jboss/portlet/hello/bean/User.java file, and the application= descriptors in the HelloWorldJSFSunRIPortlet/src/resources/hello= worldjsfsunriportlet-war/WEB-INF/ directory. - - - - - Change into HelloWorldJSFSunRIPortlet/ directo= ry, and run the ant deploy command. On Linux, the output= will be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - - - Expanding the helloworldjsfsunriportlet.war fil= e allows you to deploy the portlet as an expanded directory, which makes de= velopment easier. As well, it gives you access to the application descripto= rs, resource files, JSF, and JSP pages. To expand the helloworldj= sfsunriportlet.war file: - - - - - - If you do not have the HelloWorldJSFSunRIPortlet/hellow= orldjsfsunriportlet.war file, change into the HelloWor= ldJSFSunRIPortlet/ directory, and run the ant deploy command. This creates the helloworldjsfsunriportlet.war file. - - - - - To expand the WAR file, change into the HelloWorldJSFSu= nRIPortlet/ directory, and run the ant explode command. On Linux, the output will be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - - - The expanded WAR file and the application descriptors are located in= the HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfs= unriportlet.war/WEB-INF/ directory. + Building your JSF portlet + + The + HelloWorldJSFSunRIPortlet.zip + file contains a pre-compiled + helloworldjsfsunriportlet.war + file; however, to manually build the + helloworldjsfsunriportlet.war + file: - - - Deploying your JSF portlet - - If you did not expand the helloworldjsfsunriportlet.war file, copy the HelloWorldJSFSunRIPortlet/helloworldjsfsu= nriportlet.war file into the correct JBoss AS or JBoss EAP deploy/ directory. If you expanded the helloworld= jsfsunriportlet.war file, copy the HelloWorldJSFSunRIP= ortlet/output/lib/exploded/helloworldjsfsunriportlet.war/ direct= ory into the correct JBoss AS or JBoss EAP deploy/ dir= ectory. For example, if you are using default JBoss AS profile, copy the WAR file or the expanded directory into the = $JBOSS_HOME/server/default/deploy/ directory. - - - Performing this step on a running instance of JBoss AS or JBoss EAP,= and JBoss Portal, triggers a hot-deploy of the portlet: - - - + + + + Change into the + HelloWorldJSFSunRIPortlet/ + directory, and remove the existing + helloworldjsfsunriportlet.war + file. + + + + + If required, edit the + + HelloWorldJSFSunRIPortlet/src/main/org/jboss/po= rtlet/hello/bean/User.java + + file, and the application descriptors in the + + HelloWorldJSFSunRIPortlet/src/resources/hellowo= rldjsfsunriportlet-war/WEB-INF/ + + directory. + + + + + Change into + HelloWorldJSFSunRIPortlet/ + directory, and run the + ant deploy + command. On Linux, the output will be similar to t= he following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + Expanding the + helloworldjsfsunriportlet.war + file allows you to deploy the portlet as an expanded direct= ory, which makes + development easier. As well, it gives you access to the app= lication + descriptors, resource files, JSF, and JSP pages. To expand = the + helloworldjsfsunriportlet.war + file: + + + + + + If you do not have the + + HelloWorldJSFSunRIPortlet/helloworldjsfsunripor= tlet.war + + file, change into the + HelloWorldJSFSunRIPortlet/ + directory, and run the + ant deploy + command. This creates the + helloworldjsfsunriportlet.war + file. + + + + + To expand the WAR file, change into the + HelloWorldJSFSunRIPortlet/ + directory, and run the + ant explode + command. On Linux, the output will be similar to t= he following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + The expanded WAR file and the application descriptors are l= ocated in the + + HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworld= jsfsunriportlet.war/WEB-INF/ + + directory. + + + + Deploying your JSF portlet + + If you did not expand the + helloworldjsfsunriportlet.war + file, copy the + + HelloWorldJSFSunRIPortlet/helloworldjsfsunriportlet.war + + file into the correct JBoss AS or JBoss EAP + deploy/ + directory. If you expanded the + helloworldjsfsunriportlet.war + file, copy the + + HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworld= jsfsunriportlet.war/ + + directory into the correct JBoss AS or JBoss EAP + deploy/ + directory. For example, if you are using + default + JBoss AS profile, copy the WAR file or the expanded directo= ry into the + $JBOSS_HOME/server/default/deploy/ + directory. + + + Performing this step on a running instance of JBoss AS or J= Boss EAP, and + JBoss Portal, triggers a hot-deploy of the portlet: + + + - - - - To see the HelloWorldJSFSunRIPortlet, navigate to http://localhost:8080/portal/, or, if the= default JBoss Portal page is already open, refresh the page. The HelloWorl= dJSFSunRIPortlet is added to the bottom of the default JBoss Portal page: - - - - - - + + + + To see the HelloWorldJSFSunRIPortlet, navigate to + + http://localhost:8080/portal/ + + , or, if the default JBoss Portal page is already open, ref= resh the page. + The HelloWorldJSFSunRIPortlet is added to the bottom of the= default JBoss + Portal page: + + + + + + - - To re-deploy the portlet, for example, if you have made changes to a= ny of the application descriptors, touch the $JBOSS_HOME/server/<= replaceable>configuration/deploy/helloworldjsfsunriportlet.wa= r/WEB-INF/web.xml file. This only works if you copied the HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet= .war/ directory into the JBoss AS or JBoss EAP deploy/= directory. On Linux, run the following command to re-deploy the= HelloWorldJSFSunRIPortlet: - - - -touch $JBOSS_HOME/server/configuration/deploy/h= elloworldjsfsunriportlet.war/WEB-INF/web.xml - - - - Re-deploying the HelloWorldJSFSunRIPortlet produces output to the JBo= ss AS or JBoss EAP console, similar to the following: - - - + To re-deploy the portlet, for example, if you have made cha= nges to any of + the application descriptors, touch the + + $JBOSS_HOME/server/ + configuration + /deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml + + file. This only works if you copied the + + HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworld= jsfsunriportlet.war/ + + directory into the JBoss AS or JBoss EAP + deploy/ + directory. On Linux, run the following command to re-deploy= the + HelloWorldJSFSunRIPortlet: + + + + touch $JBOSS_HOME/server/ + configuration + /deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml + + + + Re-deploying the HelloWorldJSFSunRIPortlet produces output = to the JBoss AS + or JBoss EAP console, similar to the following: + + + - - - - + + + + + --> An example Apache MyFaces JSF portlet Introduction - - This section describes how to deploy a JSF portlet in JBoss Portal, = using the Apache MyFaces JSF implementation in JBoss AS and JBoss EAP. Befo= re proceeding, download the HelloWorl= dJSFMyFaces42Portlet from JBoss PortletSwap. - - - Apache MyFaces can be used globally for the entire server, replacing= the Sun JSF RI libraries, but the HelloWorldJSFMyFaces42Portlet uses its o= wn libraries, but does not affect the application server. - + + This section describes how to deploy a JSF portlet in JBoss= Portal, using + the Apache MyFaces JSF implementation in JBoss AS and JBoss= EAP. Before + proceeding, download the + + HelloWorldJSFMyFaces42Portlet + + from + JBoss Por= tletSwap + . + + + Apache MyFaces can be used globally for the entire server, = replacing the + Sun JSF RI libraries, but the HelloWorldJSFMyFaces42Portlet= uses its own + libraries, but does not affect the application server. + Package Structure - - JBoss Portal requires certain descriptors to be included in a portle= t WAR file. Some of these descriptors are defined by the JSR-168 Portlet Sp= ecification, and others are specific to JBoss Portal. Like a typical JSF ap= plication, the HelloWorldJSFMyFaces42Portlet package contains a f= aces-config.xml file that defines managed-beans, converters, val= idators, navigation rules, and so on. The following is an example of the di= rectory structure of the HelloWorldJSFMyFaces42Portlet portlet: - + JBoss Portal requires certain descriptors to be included in= a portlet WAR + file. Some of these descriptors are defined by the JSR-168 = Portlet + Specification, and others are specific to JBoss Portal. Lik= e a typical JSF + application, the HelloWorldJSFMyFaces42Portlet package cont= ains a + faces-config.xml + file that defines managed-beans, converters, validators, na= vigation rules, + and so on. The following is an example of the directory str= ucture of the + HelloWorldJSFMyFaces42Portlet portlet: + + - + - - - To create the WEB-INF/ and META-INF= / directories, extract the helloworldjsfmyfacesportlet= .war file. The WEB-INF/lib/ directory must = contain the Apache MyFaces libraries, along with the dependent libraries. - - - Application Descriptors - - Only the portlet.xml, faces-config.xm= l, and web.xml descriptors are described he= re. For more information about application descriptors, refer to and . - - - The following is an example of the HelloWorldJSFMyFaces42P= ortlet/WEB-INF/portlet.xml file. This file must adhere to its de= finition in the JSR-168 Portlet Specification. You may define more than one= portlet application in this file: - - - + To create the + WEB-INF/ + and + META-INF/ + directories, extract the + helloworldjsfmyfacesportlet.war + file. The + WEB-INF/lib/ + directory must contain the Apache MyFaces libraries, along = with the + dependent libraries. + + + + Application Descriptors + + Only the + portlet.xml + , + faces-config.xml + , and + web.xml + descriptors are described here. For more information about = application + descriptors, refer to + + and + + . + + + The following is an example of the + HelloWorldJSFMyFaces42Portlet/WEB-INF/portlet.xml= + file. This file must adhere to its definition in the JSR-16= 8 Portlet + Specification. You may define more than one portlet applica= tion in this + file: + + + ]]> - - - - - + + + + + + org.apache.myfaces.portlet.MyFacesGenericPortlet]]> - - - - This specifies that the org.apache.myfaces.portlet.MyFac= esGenericPortlet handles all requests and responses from t= he users. Therefore, there is no need to develop a specific portlet class, = as Apache MyFaces provides a generic implementation which bridges the JSF a= nd portlet worlds. - - - - + + + + This specifies that the + + org.apache.myfaces.portlet.MyFacesGenericPor= tlet + + handles all requests and responses from the use= rs. Therefore, + there is no need to develop a specific portlet = class, as Apache + MyFaces provides a generic implementation which= bridges the JSF + and portlet worlds. + + + + + + default-view /WEB-INF/jsp/index.jsp ]]> - - - - You must initialize the portlet with a default page to render, similar t= o a welcome page. - - - - + + + + You must initialize the portlet with a default = page to render, + similar to a welcome page. + + + + + + text/html view -]]> - - - The <supports> element all= ows you to declare all of the markup types that a portlet supports in the <= literal>render method. This is accomplished via the - <mime-type> element, which= is required for every portlet. The declared MIME types must match the capa= bility of the portlet. As well, it allows you to pair which modes and windo= w states are supported for each markup type. All portlets must support the = view portlet mode, so this does not have t= o be declared. Use the <mime-type> e= lement to define which markup type your portlet supports, which in this exa= mple, is text/html. This section tells the= portal that it only outputs text and HTML, and that it only supports the <= computeroutput>view mode. - - - - - - - - Adding Functionality to an Apache MyFaces JSF portlet - - To add functionality to an Apache MyFaces JSF portlet, sub-class it and= create your own class. - - - - - The following is an example HelloWorldJSFMyFaces42Portlet/WEB-I= NF/faces-config.xml file: - - -]]> + + + + The + <supports> + element allows you to declare all of the markup= types that a + portlet supports in the + render + method. This is accomplished via the + <mime-type> + element, which is required for every portlet. T= he declared MIME + types must match the capability of the portlet.= As well, it + allows you to pair which modes and window state= s are supported + for each markup type. All portlets must support= the + view + portlet mode, so this does not have to be decla= red. Use the + <mime-type> + element to define which markup type your portle= t supports, + which in this example, is + text/html + . This section tells the portal that it only ou= tputs text and + HTML, and that it only supports the + view + mode. + + + + + + + + Adding Functionality to an Apache MyFaces JSF por= tlet + + To add functionality to an Apache MyFaces JSF portlet= , sub-class it + and create your own class. + + + + + The following is an example + HelloWorldJSFMyFaces42Portlet/WEB-INF/faces-confi= g.xml + file: + + + ]]> - - - - Without the faces-config.xml file, the application = would work the same outside of the portlet as it would inside a portlet con= tainer. In this example, a basic user bean, <managed-bea= n-name>user</managed-bean-name>, and a navigation= rule are defined, which handle the submission of the original form in the = HelloWorldJSFMyFaces42Portlet/WEB-INF/jsp/index.jsp fi= le. - - - The following is an example of the <context-parm> element from the HelloWorldJSFMyFaces42Portlet/WE= B-INF/web.xml file: - - - + + + Without the + faces-config.xml + file, the application would work the same outside of the po= rtlet as it + would inside a portlet container. In this example, a basic = user bean, + + <managed-bean-name>user</managed-bean-name> + + , and a navigation rule are defined, which handle the submi= ssion of the + original form in the + HelloWorldJSFMyFaces42Portlet/WEB-INF/jsp/index.j= sp + file. + + + The following is an example of the + <context-parm> + element from the + HelloWorldJSFMyFaces42Portlet/WEB-INF/web.xml + file: + + + org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL true ]]> - - - - These extra parameters let the application server know that the portlet e= mbeds its own libraries. This avoids collision with the Sun JSF RI librarie= s bundled with JBoss AS and JBoss EAP. For more information, refer to the <= ulink url=3D"http://wiki.jboss.org/wiki/Wiki.jsp?page=3DJBossFaces">JBossFa= ces page on the JBoss Wiki. - - + + + + These extra parameters let the application server know that= the portlet + embeds its own libraries. This avoids collision with the Su= n JSF RI + libraries bundled with JBoss AS and JBoss EAP. For more inf= ormation, refer + to the + + JBossFaces page on the JBoss Wiki + + . + + Building your Apache MyFaces JSF portlet - - The HelloWorldJSFMyFaces42Portlet.zip file cont= ains a pre-compiled helloworldjsfmyfacesportlet.war fi= le; however, to manually build the helloworldjsfmyfacesportlet.wa= r file: - - - - - - Change into the HelloWorldJSFMyFaces42Portlet/ directory, and remove the existing helloworldjsfmyfacesportlet= .war file. - - - - - If required, edit the HelloWorldJSFMyFaces42Portlet/src= /main/org/jboss/portlet/hello/bean/User.java file, and the appli= cation descriptors in the HelloWorldJSFMyFaces42Portlet/src/resou= rces/helloworldjsfmyfacesportlet-war/WEB-INF/ directory. - - - - - Change into HelloWorldJSFMyFaces42Portlet/ d= irectory, and run the ant deploy command. On Linux, the = output will be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - - - Expanding the helloworldjsfmyfacesportlet.war f= ile allows you to deploy the portlet as an expanded directory, which makes = development easier. As well, it gives you access to the application descrip= tors, resource files, JSF, and JSP pages. To expand the helloworl= djsfmyfacesportlet.war file: - - - - - - If you do not have the HelloWorldJSFMyFaces42Portlet/he= lloworldjsfmyfacesportlet.war file, change into the He= lloWorldJSFMyFaces42Portlet/ directory, and run the ant= deploy command. This creates the helloworldjsfmyfacesp= ortlet.war file. - - - - - To expand the WAR file, change into the HelloWorldJSFMy= Faces42Portlet/ directory, and run the ant explode command. On Linux, the output will be similar to the following: - - - - - - - - - - - - - Note: the directory names will be different for your system. - - - The expanded WAR file and the application descriptors are located in= the HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworld= jsfmyfacesportlet.war/WEB-INF/ directory. - - - - Deploying your Apache MyFaces JSF portlet - - If you did not expand the helloworldjsfmyfacesportlet.war= file, copy the HelloWorldJSFMyFaces42Portlet/hellowor= ldjsfmyfacesportlet.war file into the correct JBoss AS or JBoss = EAP deploy/ directory. If you expanded the h= elloworldjsfmyfacesportlet.war file, copy the HelloWor= ldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/<= /filename> directory into the correct JBoss AS or JBoss EAP deplo= y/ directory. For example, if you are using the = default JBoss AS profile, copy the WAR file or the expande= d directory into the $JBOSS_HOME/server/default/deploy/ directory. - - - Performing this step on a running instance of JBoss AS or JBoss EAP,= and JBoss Portal, triggers a hot-deploy of the portlet. - - To see the HelloWorldJSFMyFaces42Portlet, navigate to , or, if the default JBoss Portal pag= e is already open, refresh the page. The HelloWorldJSFMyFaces42Portlet is a= dded to the bottom of the default JBoss Portal page: - - - - - - - - - - To re-deploy the portlet, for example, if you have made changes to an= y of the application descriptors, touch the $JBOSS_HOME/server/configuration/deploy/helloworldjsfmyfacesportlet.w= ar/WEB-INF/web.xml file. This only works if you copied the HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfaces= portlet.war/ directory into the JBoss AS or JBoss EAP = deploy/ directory. On Linux, run the following command to re-dep= loy the HelloWorldJSFMyFaces42Portlet: - - - -touch $JBOSS_HOME/server/configuration/deploy/h= elloworldjsfmyfacesportlet.war/WEB-INF/web.xml - = - + + The + HelloWorldJSFMyFaces42Portlet.zip + file contains a pre-compiled + helloworldjsfmyfacesportlet.war + file; however, to manually build the + helloworldjsfmyfacesportlet.war + file: + + + + + + Change into the + HelloWorldJSFMyFaces42Portlet/ + directory, and remove the existing + helloworldjsfmyfacesportlet.war + file. + + + + + If required, edit the + + HelloWorldJSFMyFaces42Portlet/src/main/org/jbos= s/portlet/hello/bean/User.java + + file, and the application descriptors in the + + HelloWorldJSFMyFaces42Portlet/src/resources/hel= loworldjsfmyfacesportlet-war/WEB-INF/ + + directory. + + + + + Change into + HelloWorldJSFMyFaces42Portlet/ + directory, and run the + ant deploy + command. On Linux, the output will be similar to t= he following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + Expanding the + helloworldjsfmyfacesportlet.war + file allows you to deploy the portlet as an expanded direct= ory, which makes + development easier. As well, it gives you access to the app= lication + descriptors, resource files, JSF, and JSP pages. To expand = the + helloworldjsfmyfacesportlet.war + file: + + + + + + If you do not have the + + HelloWorldJSFMyFaces42Portlet/helloworldjsfmyfa= cesportlet.war + + file, change into the + HelloWorldJSFMyFaces42Portlet/ + directory, and run the + ant deploy + command. This creates the + helloworldjsfmyfacesportlet.war + file. + + + + + To expand the WAR file, change into the + HelloWorldJSFMyFaces42Portlet/ + directory, and run the + ant explode + command. On Linux, the output will be similar to t= he following: + + + + + + + + + + + + Note: the directory names will be different for your sys= tem. + + The expanded WAR file and the application descriptors are l= ocated in the + + HelloWorldJSFMyFaces42Portlet/output/lib/exploded/hellow= orldjsfmyfacesportlet.war/WEB-INF/ + + directory. + + + Deploying your Apache MyFaces JSF portlet + + If you did not expand the + helloworldjsfmyfacesportlet.war + file, copy the + + HelloWorldJSFMyFaces42Portlet/helloworldjsfmyfacesportle= t.war + + file into the correct JBoss AS or JBoss EAP + deploy/ + directory. If you expanded the + helloworldjsfmyfacesportlet.war + file, copy the + + HelloWorldJSFMyFaces42Portlet/output/lib/exploded/hellow= orldjsfmyfacesportlet.war/ + + directory into the correct JBoss AS or JBoss EAP + deploy/ + directory. For example, if you are using the + default + JBoss AS profile, copy the WAR file or the expanded directo= ry into the + $JBOSS_HOME/server/default/deploy/ + directory. + + + Performing this step on a running instance of JBoss AS or J= Boss EAP, and + JBoss Portal, triggers a hot-deploy of the portlet. + + + To see the HelloWorldJSFMyFaces42Portlet, navigate to + + , or, if the default JBoss Portal page is already open, ref= resh the page. + The HelloWorldJSFMyFaces42Portlet is added to the bottom of= the default + JBoss Portal page: + + + + + + + + + + To re-deploy the portlet, for example, if you have made cha= nges to any of + the application descriptors, touch the + + $JBOSS_HOME/server/ + configuration + /deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml + + file. This only works if you copied the + + HelloWorldJSFMyFaces42Portlet/output/lib/exploded/hellow= orldjsfmyfacesportlet.war/ + + directory into the JBoss AS or JBoss EAP + deploy/ + directory. On Linux, run the following command to re-deploy= the + HelloWorldJSFMyFaces42Portlet: + + + + touch $JBOSS_HOME/server/ + configuration + /deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml + + + + + \ No newline at end of file --===============2641034271531611623==--