Author: msorokin Date: 2009-11-09 12:24:20 -0500 (Mon, 09 Nov 2009) New Revision: 18498 Modified: trunk/birt/docs/en/modules/birt_integration_with_seam.xml trunk/birt/docs/en/modules/birt_reports_deployment.xml trunk/birt/docs/en/modules/hibernate_datasource.xml trunk/birt/docs/en/modules/introduction.xml trunk/birt/docs/en/modules/tasks.xml Log: https://jira.jboss.org/jira/browse/JBIDE-4779 updated the guide Modified: trunk/birt/docs/en/modules/birt_integration_with_seam.xml =================================================================== --- trunk/birt/docs/en/modules/birt_integration_with_seam.xml 2009-11-09 17:21:44 UTC (rev 18497) +++ trunk/birt/docs/en/modules/birt_integration_with_seam.xml 2009-11-09 17:24:20 UTC (rev 18498) @@ -1,21 +1,16 @@ <?xml version='1.0' encoding='UTF-8'?> -<chapter id="birt_integration_with_seam" xreflabel="birt_integration_with_seam"> - - <?dbhtml filename="birt_integration_with_seam.html"?> - <chapterinfo> - <keywordset> - <keyword>JBoss</keyword> - <keyword>BIRT</keyword> - <keyword>Seam</keyword> - </keywordset> - </chapterinfo> +<section id="birt_integration_with_seam"> <title>Adding BIRT Functionality to Standard Seam Web Project</title> - <para>In this chapter you&apos;ll know how to create a Seam web project with BIRT - capabilities included.</para> + <para>In this section you&apos;ll know how to integrate BIRT into a Seam web project. </para> <para>You are supposed to have Seam runtime and JBoss Application Server downloaded and - extracted somewhere on you hard drive.</para> + 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> <tip> <title>Tip:</title> @@ -29,23 +24,21 @@ <section id="creatin_project_with_birt"> <title>Creating Seam Web Project with Birt Facet</title> - <para>First, open <property>Seam perspective</property> by going to <emphasis> - <property>Window &gt; Open Perspective &gt; Other &gt; Seam</property>. - </emphasis> To create a new Seam Web project follow to <emphasis> + <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> (or <emphasis> + </emphasis>. Otherwise you should go to <emphasis> + <property>File &gt; New &gt; Other &gt; Seam &gt; Seam Web Project</property> - </emphasis> if you are not in the <property>Seam perspective</property>).</para> + </emphasis> if <property>Seam</property> perspective is not active.</para> <para>On the first wizard page enter the project name, then specify the target runtime and - target server. In the <emphasis> - <property>Configuration</property> - </emphasis> section click <emphasis> - <property>Modify</property> - </emphasis> to configure the project facets.</para> + target server. We recommend to use JBoss AS server and runtime environment to ensure best performance. + </para> - <figure> + <figure id="CreatingSeamWebProject"> <title>Creating Seam Web Project</title> <mediaobject> <imageobject> @@ -54,11 +47,13 @@ </mediaobject> </figure> - <para>Choose the 2.0 version of the <emphasis> + <para>In the <emphasis><property>Configuration</property></emphasis> group choose the version of <emphasis> <property>Seam</property> - </emphasis> facet and enable the <emphasis> + </emphasis> framework you are planning to use in your application. In this guide we used Seam 2.2. </para> + <para>Click on the <emphasis><property>Modify</property></emphasis> button + and enable the <emphasis> <property>Birt Reporting Runtime Component</property> - </emphasis> facet.</para> + </emphasis> facet by checking the appropriate option.</para> <figure> <title>Adding the Birt Reporting Runtime Component Facet </title> @@ -69,9 +64,9 @@ </mediaobject> </figure> - <para>Or you can just choose the <emphasis> + <para>Alternatively you can just choose the <emphasis> <property>JBoss BIRT Integration Web Project</property> - </emphasis> configuration.</para> + </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> @@ -83,9 +78,11 @@ </mediaobject> </figure> - <para>Next two pages are filled out with defaults, just leave them through by pressing <emphasis> - <property>Next</property>.</emphasis> -On the <emphasis><property>Birt Configuration</property></emphasis> page you can modify BIRT Deployment Settings, which also defined in web.xml. Let's keep default values.</para> + <para>You may leave the next two pages with default values, just press <emphasis> + + <property>Next</property></emphasis> to proceed. + +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> @@ -95,11 +92,14 @@ </mediaobject> </figure> - <para>Next page is also filled out with default values. - On the <emphasis> + <para>You can also leave the <emphasis><property>JSF Capabilities</property></emphasis> page with default values. + On the <emphasis> <property>Seam Facet</property> - </emphasis> page you should specify the Seam runtime and Connection profile.</para> + </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> @@ -111,240 +111,98 @@ <para>Hit <emphasis> <property>Finish</property> - </emphasis> to create the project with Birt functionality enabled.</para> + </emphasis> to create the project with BIRT functionality enabled.</para> </section> <section id="integration"> <title>Integration with Seam</title> - - <para>The JBoss BIRT Integration feature contains the BIRT tag that allows the user to add a - BIRT report to an <emphasis> - <property>.xhtml</property> - </emphasis> file:</para> - - <programlisting role="XHTML"><![CDATA[<p:birt xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:p="http://jboss.com/products/seam/birt" - designType="run" - format="pdf" - designName="test.rptdesign" - title="JBoss Birt Test"> - -</p:birt>]]></programlisting> - - <para>Let&apos;s look how it works.</para> - <para>Create in the <emphasis> - <property>Web Content</property> - </emphasis> folder three <emphasis> - <property>.xhtml</property> - </emphasis> pages with the following content:</para> - +<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> <itemizedlist> - <listitem> + <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> - <emphasis> - <property>birttests.xhtml</property>:</emphasis> - </para> - <programlisting role="XHTML"><![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" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:f="http://java.sun.com/jsf/core" - xmlns:h="http://java.sun.com/jsf/html" - xmlns:rich="http://richfaces.ajax4jsf.org/rich" - template="layout/template.xhtml"> - - <ui:define name="body"> - <h:messages globalOnly="true" styleClass="message"/> - <rich:panel> - <f:facet name="header">Welcome to JBoss BIRT!</f:facet> - <ul> - <li><s:link view="/testbirt.xhtml" value="Test Birt" /></li> - <li><s:link view="/testbirt1.xhtml" value="Test Birt 1" /></li> - </ul> - </rich:panel> - </ui:define> - </ui:composition>]]></programlisting> + 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> - <emphasis> - <property>testbirt.xhtml</property>:</emphasis> - </para> - <programlisting role="XHTML"><![CDATA[<p:birt xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:p="http://jboss.com/products/seam/birt" - designType="run" - format="pdf" - designName="test.rptdesign" - title="JBoss Birt Test"> - - <p:param name="sample" value="sample param"/> -</p:birt>]]></programlisting> - </listitem> - <listitem> - <para> - <emphasis> - <property>testbirt1.xhtml</property>:</emphasis> - </para> - <programlisting role="XHTML"><![CDATA[<p:birt xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:p="http://jboss.com/products/seam/birt" - designType="frameset" - designName="test1.rptdesign" - title="JBoss Birt Test"> -</p:birt>]]></programlisting> - </listitem> </itemizedlist> - - <para>Now start the application server by clicking the <emphasis> - <property>Start</property> - </emphasis> option in the context menu of the server in the <property>JBoss Server - View</property> (if the view isn&apos;t open go to <emphasis> - <property>Window &gt; Show View &gt; Other &gt; JBoss Server - View</property>)</emphasis>. Try the tests out by accessing <emphasis> - <property>http://localhost:8080/hellobirt/birttests.seam</property> - </emphasis> in your web browser.</para> - - <figure> - <title>Welcome Page in the Browser</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/birttestsPage.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Now if you click <emphasis> - <property>Test Birt</property> - </emphasis> you should see the following <emphasis> - <property>.pdf</property> - </emphasis> file:</para> - - <figure> - <title>After Clicking Test Birt</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/testbirtPage.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>After clicking <emphasis> - <property>Test Birt 1</property> - </emphasis> the next page is displayed:</para> - - <figure> - <title>After Clicking Test Birt 1</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/testbirt1Page1.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Put the <emphasis> - <property>test param</property> - </emphasis> as Sample Parameter value, specify the maximum possible Customer Number as - <emphasis> - <property>1001</property>,</emphasis> for instance, and then press <emphasis> - <property>Ok</property>.</emphasis> You&apos;ll see the following BIRT - report:</para> - - <figure> - <title>BIRT Report in the Browser Window</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/testbirt1Page2.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>The BIRT tag recognizes most of the parameters described on <ulink - url="http://www.eclipse.org/birt/phoenix/deploy/viewerUsage2.2.php#p... - BIRT Report Viewer Parameters page</ulink>. The attributes of the BIRT tag - don&apos;t contain the <emphasis> - <property>&quot;__&quot;</property> - </emphasis> prefix.</para> - - <para>The <emphasis> - <property>param</property> - </emphasis> tag describes report parameters (see the listing for the <emphasis> - <property>testbirt.xhtml</property> - </emphasis> above). It supports the following attributes: </para> - <itemizedlist> - <listitem> - <para><emphasis> - <property>name</property> - </emphasis> - the parameter name (required)</para> - </listitem> - <listitem> - <para><emphasis> - <property>value</property> - </emphasis> - the parameter value (required)</para> - </listitem> - <listitem> - <para><emphasis> - <property>isnull</property> - </emphasis> - specifies that a report parameter has a null value - (optional)</para> - </listitem> - <listitem> - <para><emphasis> - <property>islocale</property> - </emphasis> - specifies whether the parameter is localized (optional)</para> - </listitem> - </itemizedlist> - - <para>These tags are defined in the <emphasis> - <property>org.jboss.birt.core/resources/jboss-seam-birt.jar</property> - </emphasis> library that contains source. </para> - - <para>It is also possible to embed a BIRT report in some Seam <emphasis> - <property>.xhtml</property> - </emphasis> page. See how it may be done:</para> - <para/> - + <para> - <emphasis role="bold">Example:</emphasis> + 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> + 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. [Link to tag reference] + 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[ + xmlns:b="http://jboss.com/products/seam/birt" + ]]></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> + + <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. + You can use EL expressions to bind the representation layer with back-end logic. </para> - <programlisting role="XHTML"><![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" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:f="http://java.sun.com/jsf/core" - xmlns:h="http://java.sun.com/jsf/html" - xxmlns:rich="http://richfaces.ajax4jsf.org/rich" - xmlns:b="http://jboss.com/products/seam/birt" - template="layout/template.xhtml"> - <ui:define name="body"> - <h:messages globalOnly="true" styleClass="message" id="globalMessages"/> - <rich:panel> - <f:facet name="header">Products</f:facet> - <b:birt designType="embed" designName="ProductCatalog.rptdesign" - embeddable="true" masterpage="false"/> - <div style="clear:both"/> - </rich:panel> - <div class="actionButtons"> - <s:button view="/ProductsEdit.xhtml" id="edit" value="Edit"/> - - <s:button view="/#{empty productsFrom ? 'ProductsList' : productsFrom}.xhtml" - id="done" value="Done"/> - </div> - </ui:define> -</ui:composition>]]></programlisting> + <itemizedlist> + <listitem> + + + <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" + xmlns:s="http://jboss.com/products/seam/taglib" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:rich="http://richfaces.org/rich" + xmlns:b="http://jboss.com/products/seam/birt" + template="layout/template.xhtml"> + <ui:define name="body"> + <rich:panel> + <b:birt designType="embed" designName="helloBirt.rptdesign" + embeddable="true"> + <b:param name="reportTitle" value="Customers Contacts" /> + </b:birt> + </rich:panel> + </ui:define> +</ui:composition> +...]]></programlisting> + </listitem> + </itemizedlist> + <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> + + <para>We have created a Seam project and inserted the <property>helloBirt</property> report into the <property>helloBirt.xhtml</property> view file.</para> - <para>See the result in a Browser:</para> - - <figure> - <title>Embedding BIRT Report in Seam xhtml Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_integration_with_seam/embeddedReportInSeamPage.png"/> - </imageobject> - </mediaobject> - </figure> +<para>To see that the application works correctly and as you expect, you need to launch it on the server.</para> + +<itemizedlist> + <listitem><para>In the <property>JBoss Server View </property> (If it is not open navigate to <property>Windows > Show View > Other > JBoss Server View </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></listitem> +</itemizedlist> + +<figure> + <title>Integrating BIRT into Seam Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_integration_with_seam/helloBirtproject.png"/> + </imageobject> + </mediaobject> +</figure> </section> -</chapter> +</section> \ No newline at end of file Modified: trunk/birt/docs/en/modules/birt_reports_deployment.xml =================================================================== --- trunk/birt/docs/en/modules/birt_reports_deployment.xml 2009-11-09 17:21:44 UTC (rev 18497) +++ trunk/birt/docs/en/modules/birt_reports_deployment.xml 2009-11-09 17:24:20 UTC (rev 18498) @@ -1,76 +1,155 @@ <?xml version='1.0' encoding='UTF-8'?> -<chapter id="birt_reports_deployment" xreflabel="birt_reports_deployment"> +<section id="birt_reports_deployment"> + <title>Creating a Dynamic BIRT Report</title> + + <para>The <link linkend="birt_integration_with_seam">Adding BIRT Functionality to Standard Seam Web Project</link> + and <link linkend="hibernate_datasource">Using Hibernate ODA Data Sourc</link> sections tell how to integrate a BIRT report into + a Seam web project and how to use Hibernate data source to generate a dynamic report. + In this section we will create a Seam web project that can make a dynamic report using the parameters that are defined on a web page.</para> - <?dbhtml filename="birt_reports_deployment.html"?> - <chapterinfo> - <keywordset> - <keyword>JBoss</keyword> - <keyword>BIRT</keyword> - <keyword>Seam</keyword> - </keywordset> - </chapterinfo> + <para>We will use the <property>PRODUCTS</property> table of <property>DATAMODELS</property> database for the purpose of this demo project. + In the first place, you need to generate Seam entities like we did in the previous chapter (<link linkend="hibernate_datasource">Hibernate ODA Data Source</link> ). The demo application will generate a report about the company's products, whereas it will allow to specify a product line. </para> - <title>BIRT Reports Deployment</title> + <para>The next step is to create a Java class that will store the <code>sortOrder</code> variable and its assessors, register the class in faces.config.xml. + The variable will be needed to pass dynamic data to the report via report parameters, therefore it has to be of session scope.</para> + +<para> + + + The report will print the data from the <code>Products</code> table, hence you need to create a report file first. + You can use either the <property>BIRT JDBC Data Source</property> or <property>Hibernate Data Source</property> data source to create the data set for this project. If you want to use the latter please read the previous chapter <link linkend="hibernate_datasource">Hibernate ODA Data Source</link>. +</para> + + <para> + The data set should have at least the following data set items: product vendor, product name, quantity in stock and buy price. The data is retrieved from the database with this query : + </para> + + + <programlisting role="XML"><![CDATA[ +SELECT productvedor, +productname, +quantityinstock, +buyprice +FROM Products as products - <para>When everything is configured correctly you will be able to view/render the designed - reports in your Seam (or any other) Web application.</para> +]]></programlisting> + + <para>Make a table in the report and put each data set item into a column.</para> + <para>As it was stated in the beginning of the chapter the report will be dynamic, therefore you need to declare a report parameter first, let it be <code>sortOrder</code> and to add the parameter to the query. BIRT offers rich JavaScript API, so you can modify the query programmatically like this:</para> +<programlisting role="XML"> - <para>You can deploy a report by adding an action button to the Seam&apos;s CRUD <emphasis> - <property>.xhtml</property> - </emphasis> file.</para> +&lt;xml-property name=&quot;queryText&quot;&gt;&lt;![CDATA[ +SELECT productvedor, +productname, +quantityinstock, +buyprice +FROM Products as products +]]&gt;&lt;/xml-property&gt; + &lt;method name=&quot;beforeOpen&quot;&gt;&lt;![CDATA[ +queryString = " ORDER BY products."+reportContext.getParameterValue("sortOrder")+" "+"DESC"; +this.queryText = this.queryText+queryString; +]]&gt;&lt;/method&gt; + +</programlisting> - <figure> - <title>Adding Action Button to the Seam file</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_reports_deployment/addingActionButton.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>As you can see on the figure you should have the <emphasis> - <property>testHibernateOda.xhtml</property> - </emphasis> file. It&apos;s content should be the following:</para> - - <programlisting role="XHTML"><![CDATA[<p:birt xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:p="http://jboss.com/products/seam/birt" - designType="run" - format="pdf" - designName="testHibernateOda.rptdesign" - title="JBoss Birt Test"> +<para>The report is ready. You can preview it to make sure it works properly. </para> + <para>To set the report parameter you should create an <property>.xhtml</property> view page, call it <property>Products.xhtml</property>. On the page you can set the value of the <code>sortOrder</code> Java bean variable and press the <property>Generate Report</property> button to open another view page that will display the resulted report. + </para> + <para>The source code of the <property>Products.xhtml</property> should be the following:</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" + xmlns:s="http://jboss.com/products/seam/taglib" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:h="http://java.sun.com/jsf/html" + xmlns:f="http://java.sun.com/jsf/core" + xmlns:rich="http://richfaces.org/rich" + xmlns:a4j="http://richfaces.org/a4j" template="layout/template.xhtml"> + <ui:define name="body"> + <rich:panel> + <f:facet name="header">BIRT Report Generator</f:facet> + <a4j:form ajaxSubmit="true" reRender="criterion"> + <table> + <tr> + <td>Select sort order criterion:</td> + <td><h:selectOneMenu onchange="submit()" + value="#{yourJavaBean.sortOrder}"> <!-- Bind to your Java Bean --> + <f:selectItem itemValue="buyprice" itemLabel="buy price" /> + <f:selectItem itemValue="quantityinstock" itemLabel="quantity in stock" /> + </h:selectOneMenu> + </td> + </tr> + </table> + </a4j:form> + <s:button + view="/#{!empty reportParameters.order ? 'Products' : 'ProductsReport'}.xhtml" id="generate" value="Generate Report" /> <!-- If the sertOrder variable is not set the button won't work --> + </rich:panel> + </ui:define> +</ui:composition> +]]></programlisting> + <para>The logic of the file is quite simple, when the sort order criterion is select the value of <code>yourJavaBean.sortOrder</code> + is set automatically via Ajax and the report is ready to be generated.</para> + + <para>Now you need to create the web page that will print the report, name the file <property>ProductsReport.xhtml</property>. + The file to output the report should have 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" + xmlns:s="http://jboss.com/products/seam/taglib" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:f="http://java.sun.com/jsf/core" + xmlns:h="http://java.sun.com/jsf/html" + xmlns:b="http://jboss.com/products/seam/birt" + xmlns:rich="http://richfaces.org/rich" template="layout/template.xhtml"> + <ui:define name="body"> + <rich:panel> + <f:facet name="header">Products Report</f:facet> + <b:birt designType="embed" designName="products.rptdesign" + embeddable="true" masterpage="true"> + <b:param name="sortOrder" value="#{yourJavaBean.sortOrder}" /> + </b:birt> + </rich:panel> +</ui:define> +</ui:composition> +]]></programlisting> + <para> + As you know from the <link linkend="birt_integration_with_seam">Adding BIRT Functionality to Standard Seam Web Project</link> chapter, before using the BIRT Integration framework tags on the page you need to declare the tag library and specify the name space with this line: + </para> -</p:birt> -]]></programlisting> - - <para>Next run the Seam page with embedded report on the server by right-clicking the file and - going to <emphasis> - <property>Run &gt; Run on Server</property>.</emphasis></para> - - <figure> - <title>Opening Employees.xhtml Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_reports_deployment/openingArticlesPage.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>After clicking the <emphasis> - <property>BIRT PDF Report</property> - </emphasis> button, you should see the following report:</para> - - <figure> - <title>Birt PDF Report</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/birt_reports_deployment/BirtPDFReport.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Thus, a Seam project that includes the BIRT facet can be deployed as any project. If you - define the Hibernate ODA driver, the JBoss BIRT engine will use JNDI URL that has to be bind + <programlisting role="XML"><![CDATA[ + xmlns:b="http://jboss.com/products/seam/birt" +]]></programlisting> + <para> + The dynamics to the report adds this line: + </para> + <programlisting role="XML"><![CDATA[ +<b:param name="sortOrder" value="#{yourJavaBean.sortOrder}" /> +]]></programlisting> + + <para>We bound the <code>sortOrder</code> report parameter to Java Bean variable <code>value=&quot;#{yourJavaBean.sortOrder}&quot;</code> using EL expression, and the value to the variable is assigned in the <property>Products.xhtml</property> file. </para> + <para>By default if you embed a report into HTML page the HTML-format report contains the &lt;html&gt;, + &lt;head&gt;, &lt;body&gt; etc., tags. However if your HTML page already has those tags, you can rid of them using the <code>embeddable=&quot;true&quot;</code> attribute of + + the <emphasis role="bold"><property>&lt;b:birt&gt;</property></emphasis> component.</para> + <para>Deploy the project onto the server and open your browser to see the report is successfully generated. You should navigate to + + <code>http://localhost:8080/yourProjectName/Products.seam</code> to select the criterion and press the <property>Generate Report</property> button. You will be redirected to the <code>http://localhost:8080/HelloBirt/ProductsReport.seam</code> + + </para> + <figure> + <title>Dynamic Report</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_reports_deployment/productReport.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Thus, a Seam project that includes the BIRT facet can be deployed as any project. If you + define the Hibernate ODA driver, the JBoss BIRT engine will use JNDI URL that has to be bound to either Hibernate Session Factory or Hibernate Entity Manager Factory. If you don&apos;t specify the JNDI URL property, our engine will try the following JNDI URLs:</para> @@ -89,11 +168,11 @@ <para>When creating a Seam EAR project, Hibernate Entity Manager Factory is bound to <emphasis>java:/{projectName}EntityManagerFactory</emphasis>. All you need to do is - using the Hibernate Configuration created automatically. You can use default values for the + to use the Hibernate Configuration created automatically. You can use default values for the Hibernate Configuration and JNDI URL within the BIRT Hibernate Data Source.</para> - <para>When using a Seam WAR project, neither HSF nor HEMF aren&apos;t binded to JNDI by - default. You has to do this manually. For instance, HSF can be bound to JNDI by adding the + <para>When using a Seam WAR project, neither HSF nor HEMF aren&apos;t bound to JNDI by + default. You have to do this manually. For instance, HSF can be bound to JNDI by adding the following property to the <emphasis> <property>persistence.xml</property></emphasis> file:</para> @@ -111,7 +190,8 @@ <property>WebContent/WEB-INF/platform/configuration/config.ini</property> </emphasis> file.</para> </note> - <para>In conclusion, the main goal of this document is to get you know with a full featureset + + <para>In conclusion, the main goal of this document is to get you to know with a full feature set that <property>JBoss BIRT Tools</property> provide. Thus if you have some questions, comments or suggestions on the topic, please feel free to ask in the <ulink url="http://www.jboss.org/index.html?module=bb&amp;op=viewforum&... @@ -119,4 +199,4 @@ future leaving your vote on the article <ulink url="http://www.jboss.org/community/docs/DOC-10795">Overview of the improvements required by JBossTools/JBDS Docs users</ulink>.</para> -</chapter> +</section> Modified: trunk/birt/docs/en/modules/hibernate_datasource.xml =================================================================== --- trunk/birt/docs/en/modules/hibernate_datasource.xml 2009-11-09 17:21:44 UTC (rev 18497) +++ trunk/birt/docs/en/modules/hibernate_datasource.xml 2009-11-09 17:24:20 UTC (rev 18498) @@ -1,30 +1,25 @@ <?xml version='1.0' encoding='UTF-8'?> -<chapter id="hibernate_datasource" xreflabel="hibernate_datasource"> +<section id="hibernate_datasource"> - <?dbhtml filename="hibernate_datasource.html"?> - <chapterinfo> - <keywordset> - <keyword>JBoss</keyword> - <keyword>BIRT</keyword> - <keyword>Seam</keyword> - </keywordset> - </chapterinfo> - <title>Hibernate ODA Data Source</title> + <title>Using Hibernate ODA Data Source</title> - <para>The JBoss BIRT Integration feature includes the Hibernate ODA Data Source completely - integrated with Hibernate Tools. You can use it in the way you use any of BIRT ODA drivers. - Let&apos;s perform simple actions that demonstrate it.</para> + <para>The JBoss BIRT Integration feature includes the Hibernate ODA Data Source which is completely + integrated with Hibernate Tools. You can use it the way as you would use any of BIRT ODA drivers. + + - <para>First, run the <emphasis> - <property>Seam Generate Entities</property> - </emphasis> action (You can access it from <emphasis> + + </para> + + <para>First, you need to reverse engineer from the database to generate Seam entities. You can perform this operation going to <emphasis> <property>File &gt; New &gt; Seam Generate Entities</property> </emphasis> in the <property>Seam perspective</property>. More details on the Seam Generate - Entities read in our <ulink + Entities please read <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/seam/html_... - >Seam Dev Tools Reference guide</ulink>). This action will create a Hibernate Console - configuration.</para> + >Seam Dev Tools Reference guide</ulink>). + In this guide we will use the <property>Employees</property> table of the <property>DATAMODELS</property> database. +</para> <tip> <title>Tip:</title> @@ -32,28 +27,24 @@ adjusted and connected to a database. How to do this see in the <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/seam/html_... - guide.</para> + guide.</para> + <para> + If you followed the steps described in the + <link linkend="birt_integration">Adding BIRT Functionality to Standard Seam Web Project</link> chapter, + you would have a connection profile already configured. + </para> </tip> - <para>Next add a new BIRT report. To do that navigate to <emphasis> - <property>File &gt; New &gt; Other &gt; Business Intelligence and Reporting - Tools &gt; Report</property>.</emphasis> In the <property>New Report - wizard</property> enter the report name, for instance <emphasis> - <property>testHibernateOda.rptdesign</property>,</emphasis> then click <emphasis> - <property>Finish</property>.</emphasis></para> +<para> + Next you should create a new BIRT report file ( <emphasis>><property>File &gt; New &gt; Other &gt; Business Intelligence and Reporting + Tools &gt; Report</property></emphasis>) to represent the data from the <property>Employees</property> table. Call the file <property>employees.rptdesign</property>. +</para> + - <figure> - <title>Creating a New BIRT Report </title> - <mediaobject> - <imageobject> - <imagedata fileref="images/hibernate_datasource/creatingNewBirtReport.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Now switch to the <property>Report Design perspective</property>.</para> + <para>Now switch to the <property>BIRT Report Design</property> perspective.</para> - <para>In the <property>Data Explorer View</property> right-click the <emphasis> + <para>In the <property>Data Explorer</property> view right-click the <emphasis> <property>Data Source</property> </emphasis> node and choose <emphasis> <property>New Data Source</property>.</emphasis></para> @@ -67,12 +58,12 @@ </mediaobject> </figure> - <para>In the wizard select <emphasis> + <para>The wizard will prompt you to select data source type. Choose <emphasis> <property>Hibernate Data Source</property> - </emphasis> and give it a proper name, <emphasis> - <property>HbDataSource</property> - </emphasis> for instance. Hit <emphasis> - <property>Next</property>.</emphasis></para> + </emphasis> and give it a meaningful name, for instance <emphasis> + <property>HibernateDataSource</property> + </emphasis>. Hit <emphasis> + <property>Next</property> to proceed.</emphasis></para> <figure> <title>Creating Hibernate Data Source</title> @@ -83,9 +74,14 @@ </mediaobject> </figure> - <para>On the next wizard page leave everything as it is, just press the <emphasis> + <para>On the next wizard's dialog you can leave the everything with default values, press the <emphasis> <property>Test Connection</property> - </emphasis> button to verify the connection is successful.</para> + </emphasis> button to verify that the connection is established successfully.</para> + + <para> + The <property>Hibernate Data Source</property> enables you to specify a Hibernate Configuration or JNDI URL. + + </para> <figure> <title>Hibernate Data Source Profile</title> @@ -96,33 +92,24 @@ </mediaobject> </figure> - <para>Click <emphasis> - <property>Ok</property> - </emphasis> and then <emphasis> + <para>Press <emphasis> <property>Finish</property> - </emphasis> to complete.</para> + </emphasis> to complete <property>New Data Source</property> wizard.</para> - <para>Now let&apos;s add a Hibernate ODA dataset. To do that you should bring up the - <property>New Data Set wizard</property>. In the <property>Data Explorer View</property> + <para>Now you need to configure a new Hibernate ODA data set. Launch the + <property>New Data Set</property> wizard. In the <property>Data Explorer View</property> right-click the <emphasis> <property>Data Set</property> </emphasis> node and select <emphasis> <property>New Data Set</property>.</emphasis></para> - <figure> - <title>Creating a New Data Set</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/hibernate_datasource/creatingDataSet.png"/> - </imageobject> - </mediaobject> - </figure> - <para>In the <emphasis> - <property>Data Set Name</property> - </emphasis> section specify the name. Let&apos;s it be <emphasis> - <property>HbDataSet</property>.</emphasis></para> + <para>Select <property>HibernateDataSource</property> as target data source and type in the new data set name. + Call it <property>HibernateDataSet</property>.</para> + + + <figure> <title>Creating a Hibernate ODA Data Set</title> <mediaobject> @@ -132,14 +119,26 @@ </mediaobject> </figure> - <para>Next you&apos;ll be prompted to define the query for this data set. To validate the + + <para>The next dialog of the wizard will help you compose a query for the new data set.</para> + <para>We will make a report that will print all employees in the database who has Sales Rep job title.</para> + + <programlisting role="SQL"><![CDATA[... +select jobtitle, firstname, lastname, email +from Employees as employees where employees.jobtitle = 'Sales Rep' +...]]></programlisting> + + + <para> + + To validate the entered query you can press the <emphasis> <property>Test query</property> </emphasis> button. All the HQL features like syntax highlighting, content assist, - formatting, Drag and Drop, etc., are available to you here.</para> + formatting, drag-and-drop, etc., are available to facilitate query composing.</para> <figure> - <title>Testing Query </title> + <title>Composing query for Data Set</title> <mediaobject> <imageobject> <imagedata fileref="images/hibernate_datasource/testingQuery.png"/> @@ -147,93 +146,48 @@ </mediaobject> </figure> - <para>Next the output columns will be displayed. It&apos;s possible to edit them - here.</para> + <para>Pressing <property>Finish</property> will call the <property>Edit Data Set</property> dialog where you can adjust the parameters of the data set and preview the resulted set.. + If everything looks good, hit <property>Ok</property> to generate a new data set. + </para> - <figure> - <title>HQL Features - Output Columns Section</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/hibernate_datasource/hqlFeaturesOutputColumns.png"/> - </imageobject> - </mediaobject> - </figure> + <para>Now you can insert the data set items of <property>HibernateDataSet</property> into the <property>employees.rptdesign</property>.</para> + - <para>To preview the results of the defined query click the <emphasis> - <property>Preview Results</property> - </emphasis> item.</para> - <figure> - <title>HQL Features - Preview Results Section</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/hibernate_datasource/hqlFeaturesPreviewResults.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>So far you have the Hibernate data source and data set defined. Now you can create a BIRT - report using this data source and data set.</para> - <tip> <title>Tip:</title> <para>If you don&apos;t know how to do this we suggest that you refer to the <ulink url="http://www.eclipse.org/birt/phoenix/tutorial/">Eclipse BIRT Tutorial</ulink>.</para> </tip> - <figure> - <title>Creating a BIRT Report using Created Data Source and Data Set</title> - <mediaobject> - <imageobject> - <imagedata - fileref="images/hibernate_datasource/BIRTReportUsingDataSourceAndSet.png "/> - </imageobject> - </mediaobject> - </figure> +<para>You can also use parameters in the query to add dynamics to your report. In the previous example we hardcoded the selection criterion in the <code>where</code> clause. </para> + <para>To specify the job title on-the-fly your query should look like this:</para> + <programlisting role="XML"><![CDATA[ +select jobtitle,firstname, lastname,email +from Employees as employees where employees.jobtitle = ? +]]></programlisting> + + <para>The question mark represents a data set input parameter, which is not the same as a report parameter. + Now you need to define an new report parameter to pass the data to the report, call it <code>JobTitle</code>. + + + + The dataset parameter can be linked to a report parameter. + In the <property>Data Explorer</property> view click the Data Set node to open it and right-click + on the data set you created previously( in our case it is <property>HibernateDataSet</property>), + choose <property>Edit</property> and navigate to the <property>Parameters</property> section. + Declare a new data set parameter, name it <code>jobtitle</code> and map it to the already existing <code>JobTitle</code> report parameter. + </para> - <para>If you switch to the <emphasis> - <property>Preview</property></emphasis> tab, it will run your report and show the output.</para> + <para>You report is ready, you can view it by clicking on the <property>Preview</property> tab of the <property>BIRT Report Designer</property> editor. </para> + <para>You will be prompted to assign a value to the report parameter. For instance you can enter &quot;Sales Rep&quot;. </para> <figure> - <title>BIRT Report -Preview Tab</title> + <title>Resulted Dynamic Report</title> <mediaobject> <imageobject> - <imagedata fileref="images/hibernate_datasource/BIRTReportPreviewTab.png"/> + <imagedata fileref="images/hibernate_datasource/finalReport.png"/> </imageobject> </mediaobject> </figure> - - <para>You can also use parameters within the Hibernate ODA driver.</para> - - <figure> - <title>Using Parameters within the Hibernate ODA Driver</title> - <mediaobject> - <imageobject> - <imagedata - fileref="images/hibernate_datasource/parametersWithinHibernateODADriver.png"/> - </imageobject> - </mediaobject> - </figure> - - - <figure> - <title>Adding New Parameter</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/hibernate_datasource/addingNewParameter.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Again, to preview the results switch to the <emphasis> - <property>Preview Results</property> - </emphasis> item.</para> - <figure> - <title>Previewing the Results</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/hibernate_datasource/previewingResults.png"/> - </imageobject> - </mediaobject> - </figure> - -</chapter> + +</section> Modified: trunk/birt/docs/en/modules/introduction.xml =================================================================== --- trunk/birt/docs/en/modules/introduction.xml 2009-11-09 17:21:44 UTC (rev 18497) +++ trunk/birt/docs/en/modules/introduction.xml 2009-11-09 17:24:20 UTC (rev 18498) @@ -14,6 +14,9 @@ </chapterinfo> <title>Introduction</title> + + + <section> @@ -52,87 +55,32 @@ Eclipse BIRT you&apos;ll find out in the next sections.</para> </section> -<section id="BIRT_key_features"> - <title>Key Features of BIRT</title> - <para>For a start, we propose you to look through the table of main features of BIRT plugin:</para> - <table> - - <title>Key Functionality for BIRT Plugin</title> - <tgroup cols="3"> - - <colspec colnum="1" align="left" colwidth="2*"/> - <colspec colnum="2" colwidth="4*"/> - <colspec colnum="3" align="left" colwidth="2*"/> - - <thead> - <row> - <entry>Feature</entry> - <entry>Benefit</entry> - <entry>Chapter</entry> - </row> - </thead> - - <tbody> - - <row> - <entry><para>Integration with Seam</para></entry> - <entry><para>You can add a BIRT report to an .xhtml file or embed it in some Seam .xhtml page.</para></entry> - <entry> - <link linkend="integration">integration with Seam</link> - </entry> - </row> - - <row> - <entry><para>Hibernate ODA Data Source</para></entry> - <entry><para>Hibernate ODA Data Source for the JBoss BIRT Integration feature is completely integrated with Hibernate Tools.</para></entry> - <entry> - <link linkend="hibernate_datasource">Hibernate ODA data source</link> - </entry> - </row> - - - </tbody> - - </tgroup> - </table> - - - - - - -</section> - <section> <title>JBoss BIRT Integration Functionality Overview</title> + + <para> + The key feature of JBoss BIRT Integration is the JBoss BIRT Integration Framework, which allows to integrate a BIRT report into Seam/JSF container. + The framework API reference is in the + <link linkend="framework">JBoss BIRT Integraion Framework API Reference</link> chapter of the guide. + </para> + <para> + + This guide also covers functionality of <property>JBoss Tools</property> module which assists in + integration with BIRT. + The integration plug-in allows you to visually configure <property>Hibernate Data Source</property> (specify a Hibernate configuration or JNDI URL), + compose HQL queries with syntax-highlighting, content-assist, formatting as well as other functionalities available in the HQL editor. + + + </para> - <para>This reference guide describes the one module of the <property>JBoss Tools</property> project which - performs the integration with BIRT. The integration includes the following functionalities:</para> + <para> + To enable <property>JBoss Tools</property> integration with BIRT you are intended to + have the next: + </para> <itemizedlist> <listitem> - <para>Hibernate ODA driver that includes a dialog to create HQL queries with - syntax-highlighting, content-assist, formatting as well as other functionalities - available in the HQL editor. There is also a possibility to add - parameters.</para> - </listitem> - <listitem> - <para>possibility to add JBoss BIRT functionality to the standard Seam web - project</para> - </listitem> - <listitem> - <para>BIRT JSF/Seam control</para> - </listitem> - <listitem> - <para>deployment of BIRT reports within web projects (Seam, JSF, etc.)</para> - </listitem> - </itemizedlist> - - <para>To enable <property>JBoss Tools</property> integration with BIRT you are intended to - have the next:</para> - <itemizedlist> - <listitem> <para>Eclipse with <property>JBoss Tools</property> installed (how to install <property>JBoss Tools</property> on Eclipse, what dependences and versions requirements are needed reed in the <link @@ -160,11 +108,6 @@ </note> </section> - <section id="birt_plugin_rel_resources"> - <title>Other Relevant Resources on the Topic</title> + - <para>All JBoss Developer Studio/JBoss Tools release documentation you can find at<ulink url="http://docs.jboss.org/tools/">http://docs.jboss.org/too... in the corresponding release directory.</para> - <para>The latest documentation builds are available at <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">htt... - </section> - </chapter> Modified: trunk/birt/docs/en/modules/tasks.xml =================================================================== --- trunk/birt/docs/en/modules/tasks.xml 2009-11-09 17:21:44 UTC (rev 18497) +++ trunk/birt/docs/en/modules/tasks.xml 2009-11-09 17:24:20 UTC (rev 18498) @@ -13,7 +13,7 @@ </chapterinfo> <title>Tasks</title> - <para> In this chapter of the guide you will find information on the tasks that you can perform integrating BIRT. </para> + <para> In this chapter of the guide you will find information on the tasks that you can perform integrating BIRT. The required version of BIRT is 2.3.2 or greater.</para>