[jbosstools-commits] JBoss Tools SVN: r29584 - trunk/birt/docs/en-US.

Author: mcaspers Date: 2011-03-07 17:06:55 -0500 (Mon, 07 Mar 2011) New Revision: 29584 Modified: trunk/birt/docs/en-US/birt_integration_with_seam.xml Log: "General editing and screenshot updates" Modified: trunk/birt/docs/en-US/birt_integration_with_seam.xml =================================================================== --- trunk/birt/docs/en-US/birt_integration_with_seam.xml 2011-03-07 22:06:06 UTC (rev 29583) +++ trunk/birt/docs/en-US/birt_integration_with_seam.xml 2011-03-07 22:06:55 UTC (rev 29584) @@ -1,208 +1,212 @@ <?xml version='1.0' encoding='UTF-8'?> <section id="birt_integration_with_seam"> - <title>Adding BIRT Functionality to Standard Seam Web Project</title> + <title>Adding BIRT Functionality to Standard Seam Web Project</title> - <para>In this section you&apos;ll know how to integrate BIRT into a Seam web project. </para> + <para>This section discusses the process of integrating BIRT into a Seam web project. </para> - <para>You are supposed to have Seam runtime and JBoss Application Server downloaded and - extracted on your hard drive. - You can download Seam from the - <ulink url="http://seamframework.org/Download">Seam Framework</ulink> web page and - JBoss Application Server from <ulink url="http://jboss.org/jbossas/downloads/">JBoss Application Server</ulink> official site. - + <para> + To follow this guide you will need to have the Seam runtime and JBoss Application Server downloaded and extracted on your hard drive. You can download Seam from the <ulink url="http://seamframework.org/Download">Seam Framework</ulink> web page and JBoss Application Server from <ulink url="http://jboss.org/jbossas/downloads/">JBoss Application Server</ulink> official site. </para> - <note> - <title>Tip:</title> - <para>We used <ulink - url="http://sourceforge.net/project/showfiles.php?group_id=22866&... - >JBoss Seam 2.0.1 GA</ulink> and <ulink - url="http://sourceforge.net/project/showfiles.php?group_id=22866&... - >JBoss Application Server 4.2.2 GA</ulink> in examples of this guide.</para> - </note> + <note> + <title>Tip:</title> + <para> + <ulink url="http://sourceforge.net/project/showfiles.php?group_id=22866&... Seam 2.0.1 GA</ulink> and <ulink url="http://sourceforge.net/project/showfiles.php?group_id=22866&... Application Server 4.2.2 GA</ulink> were used in the examples presented in this guide. + </para> + </note> - <section id="creatin_project_with_birt"> - <title>Creating Seam Web Project with Birt Facet</title> + <section id="creatin_project_with_birt"> + <title>Creating Seam Web Project with Birt Facet</title> - <para>We recommend to open <property>Seam perspective</property> by going to <emphasis> - <property>Window &gt; Open Perspective &gt; Other &gt; Seam</property></emphasis> , this way you will have all the tools to work with Seam at hand. - To create a new Seam Web project navigate to <emphasis> - <property>File &gt; New &gt; Seam Web Project</property> - </emphasis>. Otherwise you should go to <emphasis> - - <property>File &gt; New &gt; Other &gt; Seam &gt; Seam Web - Project</property> - </emphasis> if <property>Seam</property> perspective is not active.</para> + <para> + It is recommended that you open the Seam Perspective by selecting <menuchoice><guimenuitem>Window</guimenuitem><guimenuitem>Open Perspective</guimenuitem><guimenuitem>Other</guimenuitem><guimenuitem>Seam</guimenuitem></menuchoice>. This perspective provides conventient access to all the Seam tools. + </para> + <para> + To create a new Seam Web project select <menuchoice><guimenuitem>File</guimenuitem><guimenuitem>New</guimenuitem><guimenuitem>Seam Web Project</guimenuitem></menuchoice>. If the Seam Perspective is not active, select + <menuchoice><guimenuitem>File</guimenuitem><guimenuitem>New</guimenuitem><guimenuitem>Other</guimenuitem><guimenuitem>Seam</guimenuitem><guimenuitem>Seam Web Project</guimenuitem></menuchoice>. + </para> - <orderedlist> - - <listitem> - <para>On the first wizard page enter the project name, then specify the target runtime and + <orderedlist> + + <listitem> + <para>On the first wizard page enter the project name, then specify the target runtime and target server. We recommend to use JBoss AS server and runtime environment to ensure best performance. </para> - - <figure id="CreatingSeamWebProject"> - <title>Creating Seam Web Project</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/testBirtProject.png"/> - </imageobject> - </mediaobject> - </figure> - </listitem> - <listitem> - <para>In the <emphasis><property>Configuration</property></emphasis> group choose the version of <emphasis> + + <figure id="CreatingSeamWebProject"> + <title>Creating Seam Web Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_integration_with_seam/testBirtProject.png"/> + </imageobject> + </mediaobject> + </figure> + </listitem> + <listitem> + <para>In the <emphasis><property>Configuration</property> + </emphasis> group choose the version of <emphasis> <property>Seam</property> - </emphasis> framework you are planning to use in your application. In this guide we used Seam 2.2. </para> - </listitem> - <listitem> - <para>Click the <emphasis><property>Modify</property></emphasis> button + </emphasis> framework you are planning to use in your application. In this guide we used Seam 2.2. </para> + </listitem> + <listitem> + <para>Click the <emphasis><property>Modify</property> + </emphasis> button and enable the <emphasis> <property>Birt Reporting Runtime Component</property> - </emphasis> facet by checking the appropriate option.</para> + </emphasis> facet by checking the appropriate option.</para> - <figure> - <title>Adding the Birt Reporting Runtime Component Facet </title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/addingBirtFacet.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Alternatively you can just choose the <emphasis> + <figure> + <title>Adding the Birt Reporting Runtime Component Facet </title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_integration_with_seam/addingBirtFacet.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Alternatively you can just choose the <emphasis> <property>JBoss BIRT Integration Web Project</property> - </emphasis> configuration from the drop-down list in the <emphasis><property>Configuration</property></emphasis> group </para> - - <figure> - <title>Choosing the JBoss BIRT Integration Web Project Configuration</title> - <mediaobject> - <imageobject> - <imagedata - fileref="images/birt_integration_with_seam/projectBirtConfiguration.png"/> - </imageobject> - </mediaobject> - </figure> - - </listitem> - + </emphasis> configuration from the drop-down list in the <emphasis><property>Configuration</property> + </emphasis> group </para> + + <figure> + <title>Choosing the JBoss BIRT Integration Web Project Configuration</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_integration_with_seam/projectBirtConfiguration.png"/> + </imageobject> + </mediaobject> + </figure> + + </listitem> - <listitem> - <para>You may leave the next two pages with default values, just press <emphasis><property>Next</property></emphasis> to proceed. + + <listitem> + <para>You may leave the next two pages with default values, just press <emphasis><property>Next</property> + </emphasis> to proceed. </para> - </listitem> - - <listitem> - - <para>On the <emphasis><property>Birt Configuration</property></emphasis> page you can modify the BIRT deployment settings, which you can edit afterwards in the web.xml of the generated project. Let's keep the default values for now. + </listitem> + + <listitem> + + <para>On the <emphasis><property>Birt Configuration</property> + </emphasis> page you can modify the BIRT deployment settings, which you can edit afterwards in the web.xml of the generated project. Let's keep the default values for now. </para> - - <figure> - <title>Configuring BIRT Deployment Settings</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/birtDeploymentSettings.png"/> - </imageobject> - </mediaobject> - </figure> + + <figure> + <title>Configuring BIRT Deployment Settings</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_integration_with_seam/birtDeploymentSettings.png"/> + </imageobject> + </mediaobject> + </figure> - - </listitem> - - <listitem> - <para>You can also leave the <emphasis><property>JSF Capabilities</property></emphasis> page with default values. </para> - </listitem> - - <listitem> - <para>On the <emphasis> + + </listitem> + + <listitem> + <para>You can also leave the <emphasis><property>JSF Capabilities</property> + </emphasis> page with default values. </para> + </listitem> + + <listitem> + <para>On the <emphasis> <property>Seam Facet</property> - </emphasis> page you should specify the Seam runtime and Connection profile. Please note, that the Seam runtime must be of the version you initially specified in the project settings (See the <link linkend="CreatingSeamWebProject">Creating Seam Web Project</link> figure). </para> - <para> When creating a Seam project with BIRT capabilities you can use the <property>BIRT Classic Models Sample Database</property> connection profile to work with the BIRT sample database.</para> - - <para>For more details on how to configure database connection for a Seam project please read the + </emphasis> page you should specify the Seam runtime and Connection profile. Please note, that the Seam runtime must be of the version you initially specified in the project settings (See the <link linkend="CreatingSeamWebProject">Creating Seam Web Project</link> figure). </para> + <para> When creating a Seam project with BIRT capabilities you can use the <property>BIRT Classic Models Sample Database</property> connection profile to work with the BIRT sample database.</para> + + <para>For more details on how to configure database connection for a Seam project please read the <ulink url="http://docs.jboss.org/tools/3.0.0.GA/en/seam/html_single/index.... Seam Facet Settings</ulink> chapter of Seam Dev Tools Reference Guide.</para> - <figure> - <title>Configuring the Seam Facet settings</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/seamFacet.png"/> - </imageobject> - </mediaobject> - </figure> - - </listitem> - + <figure> + <title>Configuring the Seam Facet settings</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_integration_with_seam/seamFacet.png"/> + </imageobject> + </mediaobject> + </figure> + + </listitem> - <listitem> - <para>Hit <emphasis> + + <listitem> + <para>Hit <emphasis> <property>Finish</property> - </emphasis> to create the project with BIRT functionality enabled.</para> - </listitem> - </orderedlist> - </section> + </emphasis> to create the project with BIRT functionality enabled.</para> + </listitem> + </orderedlist> + </section> - <section id="integration"> - <title>Integration with Seam</title> -<para> + <section id="integration"> + <title>Integration with Seam</title> + <para> In the previous section you have created a Seam project with BIRT capabilities. Now you can create a simple kick start project to see that everything is configured correctly. </para> - - <orderedlist> - <listitem><para>Now create a BIRT report file and insert test data into the file. + + <orderedlist> + <listitem> + <para>Now create a BIRT report file and insert test data into the file. Name the report file <property>helloBirt.rptdesign</property>, the report should print the data from the <code>CLASSICMODELS.CUSTOMERS</code> table of the <property>BIRT Classic Models Sample Database</property>, namely: customer number (<code>CLASSICMODELS.CUSTOMERS.CUSTOMERNAME</code>), contact person first name ( <code>CLASSICMODELS.CUSTOMERS.CONTACTFIRSTNAME</code>) , contact person last name (<code>CLASSICMODELS.CUSTOMERS.CONTACTLASTNAME</code>) and contact person phone number(<code>CLASSICMODELS.CUSTOMERS.PHONE</code>). </para> - <para>The title of the report should be set via <code>reportTitle</code> parameter</para> - <para> + <para>The title of the report should be set via <code>reportTitle</code> parameter</para> + <para> As this guide is primarily focused on the BIRT integration and not the BIRT technology itself we will not show the steps required to make the report. If you do not feel strong about creating a BIRT report file please read <ulink url="http://eclipse.org/birt/phoenix/tutorial/">BIRT documentation</ulink>. - </para> - <para>You can download the file <property>helloBirt.rptdesign</property> <ulink url="files/helloBirt.rptdesign">here</ulink> and copy it to the WebContent folder of your Seam project.</para> - - </listitem> - - <listitem> - <para> + </para> + <para>You can download the file <property>helloBirt.rptdesign</property> + <ulink url="files/helloBirt.rptdesign">here</ulink> and copy it to the WebContent folder of your Seam project.</para> + + </listitem> + + <listitem> + <para> When you are done with the <property>helloBirt.rptdesign</property> file, you should create a <property>.xhtml</property> file that will contain the BIRT report you have just created. - </para> - + </para> - <para> - The JBoss BIRT Integration framework provides 2 components represented as <emphasis role="bold"> <property>&lt;b:birt&gt;</property></emphasis> and <emphasis role="bold"> <property>&lt;b:param&gt;</property></emphasis> tags. The jboss-seam-birt.jar library implements the functionality of the components. To find more information about the framework pleas read the <link linkend="framework">JBoss BIRT Integraion Framework API Reference</link> chapter. + + <para> + The JBoss BIRT Integration framework provides 2 components represented as <emphasis role="bold"> <property>&lt;b:birt&gt;</property> + </emphasis> and <emphasis role="bold"> <property>&lt;b:param&gt;</property> + </emphasis> tags. The jboss-seam-birt.jar library implements the functionality of the components. To find more information about the framework pleas read the <link linkend="framework">JBoss BIRT Integraion Framework API Reference</link> chapter. To use that tags on the page you need to declare the tag library and define the name space like this: </para> + - - <programlisting role="XML"><![CDATA[ + <programlisting role="XML"><![CDATA[ xmlns:b="http://jboss.com/products/seam/birt" - ]]></programlisting> + ]]></programlisting> - <para> - The <emphasis role="bold"> <property>&lt;b:birt&gt;</property></emphasis> is a container for a BIRT report, that helps you integrate the report into Seam environment. - You can manage the properties of the report using the attributes of the <emphasis role="bold"> <property>&lt;b:birt&gt;</property></emphasis> tag. + <para> + The <emphasis role="bold"> <property>&lt;b:birt&gt;</property> + </emphasis> is a container for a BIRT report, that helps you integrate the report into Seam environment. + You can manage the properties of the report using the attributes of the <emphasis role="bold"> <property>&lt;b:birt&gt;</property> + </emphasis> tag. </para> - - <para> + + <para> - The <emphasis role="bold"> <property>&lt;b:param&gt;</property></emphasis> tag describes report parameters. To set a parameter you need to specify it's name the value you want to pass. + The <emphasis role="bold"> <property>&lt;b:param&gt;</property> + </emphasis> tag describes report parameters. To set a parameter you need to specify it's name the value you want to pass. You can use EL expressions to bind the representation layer with back-end logic. </para> - - </listitem> + </listitem> - <listitem> + + <listitem> - - <para>Create the <property>helloBirt.xhtml</property> file in the WebContent with the following content: </para> - - <programlisting role="XML"><![CDATA[... + + <para>Create the <property>helloBirt.xhtml</property> file in the WebContent with the following content: </para> + + <programlisting role="XML"><![CDATA[... <!DOCTYPE composition PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <ui:composition xmlns="http://www.w3.org/1999/xhtml" @@ -220,36 +224,40 @@ </rich:panel> </ui:define> </ui:composition> -...]]></programlisting> - - <para>From this listing above you see that the title of the report is set via <emphasis role="bold"> <property>&lt;b:param&gt;</property></emphasis> by setting the parameter name and defining the <emphasis><property>&quot;value&quot;</property></emphasis> attribute with the &quot;Customers Contacts&quot; value.</para> - - </listitem> - +...]]></programlisting> + + <para>From this listing above you see that the title of the report is set via <emphasis role="bold"> <property>&lt;b:param&gt;</property> + </emphasis> by setting the parameter name and defining the <emphasis><property>&quot;value&quot;</property> + </emphasis> attribute with the &quot;Customers Contacts&quot; value.</para> + + </listitem> - <listitem> - <para>We have created a Seam project and inserted the <property>helloBirt</property> report into the <property>helloBirt.xhtml</property> view file.</para> + + <listitem> + <para>We have created a Seam project and inserted the <property>helloBirt</property> report into the <property>helloBirt.xhtml</property> view file.</para> - -<para>To see that the application works correctly and as you expect, you need to launch it on the server.</para> - </listitem> - <listitem><para>In the <property>Servers</property> view (If it is not open navigate to <property>Windows > Show View > Other > Server > Servers</property>), select the server the application is deployed to and hit the <property>Start</property> button. </para></listitem> - <listitem> - <para>When the server is started, open your favourite browser and point it to <code>http://localhost:8080/HelloBirt/helloBirt.seam</code> .</para> + + <para>To see that the application works correctly and as you expect, you need to launch it on the server.</para> + </listitem> + <listitem> + <para>In the <property>Servers</property> view (If it is not open navigate to <property>Windows > Show View > Other > Server > Servers</property>), select the server the application is deployed to and hit the <property>Start</property> button. </para> + </listitem> + <listitem> + <para>When the server is started, open your favourite browser and point it to <code>http://localhost:8080/HelloBirt/helloBirt.seam</code> .</para> - -<figure> - <title>Integrating BIRT into Seam Project</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/helloBirtproject.png"/> - </imageobject> - </mediaobject> -</figure> - </listitem> - </orderedlist> - - </section> + + <figure> + <title>Integrating BIRT into Seam Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_integration_with_seam/helloBirtproject.png"/> + </imageobject> + </mediaobject> + </figure> + </listitem> + </orderedlist> + + </section> </section> \ No newline at end of file