Author: ochikvina Date: 2008-11-25 09:20:30 -0500 (Tue, 25 Nov 2008) New Revision: 12010 Added: trunk/portlet/docs/reference/en/modules/jsf_seam_portlets.xml trunk/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml Modified: trunk/portlet/docs/reference/en/modules/intro.xml trunk/portlet/docs/reference/en/modules/starting_project.xml Log: https://jira.jboss.org/jira/browse/JBDS-479 - add new info about JBoss Portlets; Modified: trunk/portlet/docs/reference/en/modules/intro.xml =================================================================== --- trunk/portlet/docs/reference/en/modules/intro.xml 2008-11-25 14:16:41 UTC (rev 12009) +++ trunk/portlet/docs/reference/en/modules/intro.xml 2008-11-25 14:20:30 UTC (rev 12010) @@ -77,7 +77,7 @@ Bridge</para> </entry> <entry> - <link linkend="adding_JsfSeam_portlet">Adding JSF/Seam Portlet to a + <link linkend="jsf_seam_portlets">Adding JSF/Seam Portlet to a project</link> </entry> </row> Added: trunk/portlet/docs/reference/en/modules/jsf_seam_portlets.xml =================================================================== --- trunk/portlet/docs/reference/en/modules/jsf_seam_portlets.xml (rev 0) +++ trunk/portlet/docs/reference/en/modules/jsf_seam_portlets.xml 2008-11-25 14:20:30 UTC (rev 12010) @@ -0,0 +1,229 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="jsf_seam_portlets" xreflabel="jsf_seam_portlets"> + <?dbhtml filename="jsf_seam_portlets.html"?> + <title>Adding JSF/Seam Portlets to a Dynamic Web Project</title> + + <para>This chapter will explain how you can configure JSF and Seam Portlets within Dynamic Web + Project by using the wizards <property>JBoss Tools</property> provides.</para> + + <section id="jsf_portlet"> + <title>Adding JSF Portlet to a Dynamic Web Project</title> + <para>To add JSF Portlet to a Dynamic Web Project, you should set the Configuration to <emphasis> + <property>JavaServer Faces v1.1 Project</property> + </emphasis> or <emphasis> + <property>JavaServer Faces v1.2 Project</property> + </emphasis> and configure the JSF Portlet Facets in the <property>New Dynamic Web + Project wizard</property> by clicking the <emphasis> + <property>Modify</property> + </emphasis> button.</para> + + <figure> + <title>Setting the JSF Configuration</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets1.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>On the Project Facets dialog you should select <property>JBoss Core Portlet</property> + and <property>JBoss JSF Portlet</property> check boxes.</para> + + <figure> + <title>Enabling the Portlet Facets</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets2.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Next wizard page is for configuring JSF Capabilities. You can leave everything as it + is here.</para> + + <figure> + <title>JSF Capabilities</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets3.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>To support Portlets in JSF/Seam applications <property>JBoss Tools</property> works + with <property>JBoss Portlet Bridge</property>. Thus on the next page you should add JSF Portlet + capabilities by pointing to the Portletbridge Runtime location.</para> + + <figure> + <title>JSF Capabilities</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets4.png"/> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + + <para>You can download JBoss Portlet Bridge 1.0.0.B4 from <ulink + url="http://www.jboss.org/portletbridge/download/">here</... + </tip> + + <para>Next click <emphasis> + <property>Finish</property> + </emphasis> to organize the Project.</para> + <para id="add_jsf_portlet">To add JSF Portlet to generated project you should call the + <property>Create Portlet wizard</property> by navigating to <emphasis> + <property>New > Other > JBoss Tools Web > Portlet > JSF/Seam + Portlet</property>.</emphasis></para> + + <figure> + <title>Calling New Portlet Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets5.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>As you see, the Seam and JSF Portlet wizards are merged into one. We set JSF + Configuration for the project, so default values in this wizard will be set as for a JSF + portlet.</para> + + <figure> + <title>Creating JSF Portlet</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets6.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Click <emphasis> + <property>Finish</property> + </emphasis> to complete JSF Portlet creation. Now you can deploy the project the same + way as it was <link linkend="deploying_to_portal">described above</link>.</para> + + <para>In the Browser JSF Portlet looks as follows.</para> + + <figure> + <title>JSF Portlet in the Browser</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets7.png"/> + </imageobject> + </mediaobject> + </figure> + </section> + + <section id="seam_portlet"> + <title>Adding Seam Portlet to a Dynamic Web Project</title> + + <para>To add Seam Portlet to a Dynamic Web Project first you should organize New Dynamic Web + Project with the Configuration setting to <emphasis> + <property>JBoss Seam Portlet Project v2.0</property>.</emphasis></para> + + <figure> + <title>Calling New Portlet Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets8.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>It will add all needed facets to your project. By clicking the <emphasis> + <property>Modify</property> + </emphasis> button you can observe the chosen configuration of facets as well as modify + it. As you can see, all JBoss Portlets are checked.</para> + + <figure> + <title>Project Facets</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets9.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Next wizard pages are for adjusting the Project Web Modules and JSF Configuration. + They include default values, so you can skip them by pressing <emphasis> + <property>Next</property>.</emphasis></para> + + <para>On the <property>Seam Facet</property> page <ulink url="&seamlink;#seamFacet">set + Connection Profile</ulink> and hit <emphasis> + <property>Next</property>.</emphasis></para> + + <figure> + <title>Seam Facet Settings</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets10.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Last wizard page will prompt you to set the path to Portletbridge Runtime + location.</para> + + <figure> + <title>Setting the Portletbridge Runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets11.png"/> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + + <para>Thus you should have JBoss Portlet Bridge downloaded and extracted somewhere on + your hard drive. You can download JBoss Portlet Bridge 1.0.0.B4 from <ulink + url="http://www.jboss.org/portletbridge/download/">here</... + </tip> + + <para>Now, to add Seam Portlet to the project you should follow to <emphasis> + <property>New > Other > JBoss Tools Web > Portlet > JSF/Seam + Portlet</property>.</emphasis> This will call the wizard for creating JSF/Seam + Portlets.</para> + + <figure> + <title>Calling the Create Portlet Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets12.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>As we set Seam Configuration for the Dynamic Web Project, the wizard puts the values + as for Seam Portlet.</para> + + <figure> + <title>Creating Seam Portlet</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets13.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>After creating the Seam Portlet, you should <link linkend="deploying_to_portal">deploy + the project to JBoss Portal</link> and start the Server. In a Browser + you&apos;ll see the following:</para> + + <figure> + <title>Seam Portlet in the Browser</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_seam_portlets/jsf_seam_portlets14.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Thus in this chapter you&apos;ve learnt how to add JSF/Seam Portlets to a Dynamic + Web Project.</para> + </section> +</chapter> Added: trunk/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml =================================================================== --- trunk/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml (rev 0) +++ trunk/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml 2008-11-25 14:20:30 UTC (rev 12010) @@ -0,0 +1,118 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="portlets_to_nonWTP_projects" xreflabel="portlets_to_nonWTP_projects"> + <?dbhtml filename="portlets_to_nonWTP_projects.html"?> + <title>Adding Portlets to non-WTP Projects</title> + + <para>Starting from <property>JBoss Tools 3.0.0.Beta1</property> version the JBoss Portlet + wizards no longer require a WTP project to be able to create Portlets. Hence, in this + chapter we will consider the steps to perform in order to add a Portlet to non-WTP projects + such as JSF Project and Seam Project.</para> + + <note> + <title>Note:</title> + <para>Please note, if the project does not have the proper portlet API jar's, the generated + classes will have compile errors.</para> + </note> + + <section id="jsf_portlet_to_nonWTP_project"> + <title>Adding a Portlet to the JSF Project</title> + <para>How to organize a JSF Project you can find out in our <ulink + url="&jsfreflink;#new_jsf_project">JSF Tools Reference Guide</ulink>. Just + remember to point Target Runtime to JBoss Portal directory location.</para> + + <figure> + <title>Creating New JSF Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/non_wtp/non_wtp1.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Before adding a Portlet to the project you should enable necessary facets for it. + Right-click the created project and click <emphasis> + <property>Preferences</property> + </emphasis> to open the <property>Project Preferences</property> screen.</para> + <para>On the <property>Project Facets</property> page select the <emphasis> + <property>JBoss Core Portlet</property> + </emphasis> and <emphasis> + <property>JBoss JSF Portlet</property> + </emphasis> checkboxes. And then the screen will ask you to enable <emphasis> + <property>JavaServer Faces</property> + </emphasis> facet as well.</para> + + <figure> + <title>Project Facets</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/non_wtp/non_wtp2.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Notice, <emphasis> + <property>&quot;Further configuration required...&quot;</property> + </emphasis> warning appears at the bottom of the screen. It means that you should click + it to configure JSF and JSF Portlet Capabilities in the project.</para> + + <figure> + <title>JSF Capabilities</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/non_wtp/non_wtp3.png"/> + </imageobject> + </mediaobject> + </figure> + + <figure> + <title>Project Facets</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/non_wtp/non_wtp4.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>After setting the path to Portletbridge Runtime location, click <emphasis> + <property>OK</property> + </emphasis> and then <emphasis> + <property>OK</property> + </emphasis> again.</para> + + <para>Now you can add JSF Portlet to the generated JSF Project. How to do it we showed in + <link linkend="add_jsf_portlet">the previous chapter</link>.</para> + </section> + + <section id="seam_portlet_to_nonWTP_project"> + <title>Adding a Portlet to the Seam Project</title> + <para>First start a Seam Project by following to <emphasis> + <property>New > Other > Seam > Seam Web Project</property>. </emphasis> On the first + wizard page specify JBoss Portal directory location as <property>Target + Runtime</property> and <emphasis> + <property>JBoss Seam Portlet Project v2.0</property> + </emphasis> as <property>Configuration</property>.</para> + + <figure> + <title>Project Facets</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/non_wtp/non_wtp5.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Next steps will be the same as we did for the Dynamic Web Project in the <link + linkend="seam_portlet">Adding Seam Portlet to a Dynamic Web Project</link> + section.</para> + + <para>In conclusion, with this document you&apos;ve learnt how to get started with <property>JBoss + Portal</property> using <property>JBoss Tools</property> suite of Eclipse plugins. + The above chapters walked you through the steps on how to organize a web project with + portlets which includes a sample staff and deploy it onto the <property>JBoss + Portal</property>.</para> + + <para>If you still have questions or suggestions you are always welcome on our <ulink + url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... + >Forum</ulink>. Your feedback will be very much appreciated.</para> + </section> +</chapter> Modified: trunk/portlet/docs/reference/en/modules/starting_project.xml =================================================================== --- trunk/portlet/docs/reference/en/modules/starting_project.xml 2008-11-25 14:16:41 UTC (rev 12009) +++ trunk/portlet/docs/reference/en/modules/starting_project.xml 2008-11-25 14:20:30 UTC (rev 12010) @@ -5,7 +5,9 @@ <para>To get started with <property>JBoss Portal</property> and <property>JBoss Tools</property>, you should first have a Web Project pointed to the JBoss Portal Runtime. - Thus, this chapter is intended to give you a detail look at how you can get it.</para> + Thus, in this chapter we are going to show you how to create a + Dynamic Web Project, add Java Portlet to it and deploy it to the <property>JBoss + Portal</property>.</para> <section id="creating_project_with_jbossportal"> <title>Creating a Dynamic Web Project</title> @@ -25,12 +27,12 @@ </mediaobject> </figure> - <para>Fill in the name of your project. Next, click on the <emphasis> - <property>New...</property> + <para>Fill out the name of your project. Next, click the <emphasis> + <property>New</property> </emphasis> button in the <emphasis> <property>Target Runtime</property> - </emphasis> section to specify a new Target Runtime. Click <emphasis>Jboss 4.2 - Runtime</emphasis> and press <emphasis> + </emphasis> section to specify a new Target Runtime. Click <emphasis>JBoss 4.2 + Runtime</emphasis> and press <emphasis> <property>Next</property>.</emphasis></para> <figure> @@ -63,13 +65,19 @@ </mediaobject> </figure> - <para>Click on <emphasis> - <property>Finish</property>.</emphasis> It returns you to the <property>New Dynamic - Web Project</property> wizard where it&apos;s also necessary to set the project + <para>Click <emphasis> + <property>Finish</property>.</emphasis></para> + + <para>On the next step you should click the <emphasis> + <property>Modify</property> + </emphasis> button next to the <property>Configuration</property> section to enable Portlet + Facets for the project.</para> + + <!--para>where it&apos;s also necessary to set the project Configuration. <property>JBoss Tools</property> (starting from 3.0.0.Alpha1) support the JSR-168 Portlet Specification (Portlet 1.0), JSR-286 Portlet Specification (Portlet 2.0). Thus you can choose <emphasis>Portlet Project v1.0</emphasis> or <emphasis>Portlet - Project v2.0</emphasis>.</para> + Project v2.0</emphasis>.</para--> <figure> <title>Setting the Project Configuration</title> @@ -80,6 +88,21 @@ </mediaobject> </figure> + <para>On this page you should check the <emphasis> + <property>JBoss Core Portlet</property> + </emphasis> and press <emphasis> + <property>OK</property> + </emphasis>.</para> + + <figure> + <title>Enabling the Portlet Facet</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_4_a.png"/> + </imageobject> + </mediaobject> + </figure> + <para>The last wizard page is for configuring web modules. Here all values are set, so you can leave everything as it is.</para> @@ -114,10 +137,165 @@ </mediaobject> </figure> - <para>Here <property>JBoos Tools</property> have added JBoss - Portlet facet to the project, created an empty <emphasis> + <para>Here <property>JBoos Tools</property> added JBoss Portlet facet to the project, + created an empty <emphasis> <property>portlet.xml</property> - </emphasis> file and added the portlet library to the project classpath.</para> + </emphasis> file and added the Portlet library to the project classpath.</para> </section> + <section id="adding_java_portlet"> + <title>Adding a Java Portlet to the Project</title> + + <para>At this point we&apos;ll show what the steps you need to proceed to add a new Java Portlet + to the project.</para> + + <para>Call the <property>Create Portlet wizard</property> by selecting <emphasis> + <property>New > Other > JBoss Tools Web > Portlet > Java + Portlet</property>.</emphasis></para> + + <figure> + <title>New Java Portlet</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_1.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>The wizard fills in the Web Project and Source Folder fields for you. Then you need to + specify the Java package and the Class name and click <emphasis> + <property>Next</property> + </emphasis>.</para> + + <figure> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_2.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>On the other page you will be able to set the display name of the Portlet, a title, a + description, the supported modes and init parameters.</para> + + <figure> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_3.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>On the next screen you can define which methods from + <emphasis>GenericPortlet</emphasis> you want to override.</para> + + <figure> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_4.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>The last screen lets you build <property>JBoss Portal</property> specific descriptors + to create an instance during the deployment and place it directly on the Portal.</para> + + <figure> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_5.png"/> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + + <para>If you uncheck the <emphasis> Create Portlet Instance</emphasis> checkbox, + <property>JBoss Tools</property> won&apos;t create the deployment elements + in the <emphasis> default-object.xml</emphasis> and <emphasis> + portlet-instances.xml</emphasis> files.</para> + </tip> + + <para>Once Java Portlet is created, new resources have been added to the project structure. + As you can see on the figure below, it adds a Java Portlet class (<emphasis> + <property>TestPortlet.java</property> + </emphasis> in our case), <emphasis> + <property>default-object.xml</property> + </emphasis> and <emphasis> + <property>portlet-instances.xml</property> + </emphasis> files and updates <emphasis> + <property>portlet.xml</property> + </emphasis> as well.</para> + + <figure> + <title>The structure of Web Project with Java Portlet created</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_6.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Thus, now the Project is ready to be built and deployed.</para> + </section> + + <section id="deploying_to_portal"> + <title>Deploying a Portlet to JBoss Portal</title> + + <para>You can deploy the created project in the way you deploy any other Web Application. + Right click on the project and do <emphasis> + <property>Run As > Run On Server</property> + </emphasis> and accept the defaults. On the <emphasis> + <property>Add and Remove Projects</property> + </emphasis> page move the created Project to the right and click <emphasis> + <property>Finish</property>.</emphasis></para> + + <figure> + <title>Deploying the Portlet Application</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_11.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>It will deploy the Portlet Web Application and start <property>JBoss + AS</property>.</para> + + <tip> + <title>Tip:</title> + + <para>You should use <emphasis>http://localhost:8080/portal</emphasis> URL to see your + Portlet in the Browser.</para> + </tip> + + <figure> + <title>Java Portlet in the Browser Window</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_12.png"/> + </imageobject> + </mediaobject> + </figure> + + <!--para>The JSF Portlet looks in the Browser as follows.</para> + + <figure> + <title>JSF Portlet in the Browser Window</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/portlets_support/portlets_support_13.png"/> + </imageobject> + </mediaobject> + </figure--> + + <para>This way just created Portlet looks in the Browser. </para> + + </section> + </chapter>