Author: msorokin Date: 2009-11-16 12:16:13 -0500 (Mon, 16 Nov 2009) New Revision: 18706 Modified: trunk/birt/docs/en/master.xml 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 Log: https://jira.jboss.org/jira/browse/JBIDE-4779 updated the guide Modified: trunk/birt/docs/en/master.xml =================================================================== --- trunk/birt/docs/en/master.xml 2009-11-16 16:41:17 UTC (rev 18705) +++ trunk/birt/docs/en/master.xml 2009-11-16 17:16:13 UTC (rev 18706) @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" -"http://www.docbook.org/xml/4.3/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN" +"http://www.docbook.org/xml/5.0/dtd/docbook.dtd" [ <!ENTITY introduction SYSTEM "modules/introduction.xml"> Modified: trunk/birt/docs/en/modules/birt_integration_with_seam.xml =================================================================== --- trunk/birt/docs/en/modules/birt_integration_with_seam.xml 2009-11-16 16:41:17 UTC (rev 18705) +++ trunk/birt/docs/en/modules/birt_integration_with_seam.xml 2009-11-16 17:16:13 UTC (rev 18706) @@ -34,10 +34,14 @@ Project</property> </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 + <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> @@ -46,11 +50,14 @@ </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> - <para>Click on the <emphasis><property>Modify</property></emphasis> button + </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> @@ -63,55 +70,76 @@ </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> - - <para>You may leave the next two pages with default values, just press <emphasis> + <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> - <property>Next</property></emphasis> to proceed. + <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. + </para> + </listitem> -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> - - <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. 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> + + <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> + + + + </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 + <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> + + + <listitem> <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> + </listitem> + </orderedlist> </section> <section id="integration"> @@ -120,7 +148,9 @@ 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> + + + <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>) , @@ -134,30 +164,39 @@ <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> - </itemizedlist> - + + <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> - 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] + </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. 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[ + </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> - <itemizedlist> + + </listitem> + + + + <listitem> @@ -182,19 +221,25 @@ </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>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> + + <para>To see that the application works correctly and as you expect, you need to launch it on the server.</para> - -<itemizedlist> + </listitem> <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> + <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> @@ -203,6 +248,8 @@ </imageobject> </mediaobject> </figure> - + </listitem> + </orderedlist> + </section> </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-16 16:41:17 UTC (rev 18705) +++ trunk/birt/docs/en/modules/birt_reports_deployment.xml 2009-11-16 17:16:13 UTC (rev 18706) @@ -7,19 +7,25 @@ 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> + <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> +<orderedlist> + <listitem> <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> + </listitem> + + <listitem> + <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> @@ -33,9 +39,12 @@ FROM Products as products ]]></programlisting> - + </listitem> + <listitem> <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> + </listitem> + <listitem> + <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"> &lt;xml-property name=&quot;queryText&quot;&gt;&lt;![CDATA[ @@ -51,10 +60,14 @@ ]]&gt;&lt;/method&gt; </programlisting> - + </listitem> + <listitem> <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> + </listitem> + <listitem> <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[ @@ -91,7 +104,8 @@ ]]></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> - + </listitem> + <listitem> <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> @@ -135,7 +149,9 @@ &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 + </listitem> + <listitem> + <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> @@ -148,6 +164,8 @@ </imageobject> </mediaobject> </figure> + </listitem> +</orderedlist> <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 Modified: trunk/birt/docs/en/modules/hibernate_datasource.xml =================================================================== --- trunk/birt/docs/en/modules/hibernate_datasource.xml 2009-11-16 16:41:17 UTC (rev 18705) +++ trunk/birt/docs/en/modules/hibernate_datasource.xml 2009-11-16 17:16:13 UTC (rev 18706) @@ -6,12 +6,11 @@ <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> +<orderedlist> + <listitem> <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 @@ -34,16 +33,20 @@ you would have a connection profile already configured. </para> </tip> - + </listitem> + <listitem> <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> + </listitem> + +<listitem> + - - <para>Now switch to the <property>BIRT Report Design</property> perspective.</para> - +</listitem> + <listitem> <para>In the <property>Data Explorer</property> view right-click the <emphasis> <property>Data Source</property> </emphasis> node and choose <emphasis> @@ -57,7 +60,8 @@ </imageobject> </mediaobject> </figure> - +</listitem> + <listitem> <para>The wizard will prompt you to select data source type. Choose <emphasis> <property>Hibernate Data Source</property> </emphasis> and give it a meaningful name, for instance <emphasis> @@ -73,7 +77,8 @@ </imageobject> </mediaobject> </figure> - + </listitem> + <listitem> <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 that the connection is established successfully.</para> @@ -91,11 +96,14 @@ </imageobject> </mediaobject> </figure> - + </listitem> + <listitem> <para>Press <emphasis> <property>Finish</property> </emphasis> to complete <property>New Data Source</property> wizard.</para> - + </listitem> + + <listitem> <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> @@ -103,7 +111,8 @@ </emphasis> node and select <emphasis> <property>New Data Set</property>.</emphasis></para> - + </listitem> + <listitem> <para>Select <property>HibernateDataSource</property> as target data source and type in the new data set name. Call it <property>HibernateDataSet</property>.</para> @@ -118,8 +127,9 @@ </imageobject> </mediaobject> </figure> + </listitem> + <listitem> - <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> @@ -128,7 +138,8 @@ from Employees as employees where employees.jobtitle = 'Sales Rep' ...]]></programlisting> - + + <para> To validate the @@ -145,11 +156,15 @@ </imageobject> </mediaobject> </figure> - - <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.. + </listitem> + <listitem> + + <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> - + </listitem> + <listitem> + <para>Now you can insert the data set items of <property>HibernateDataSet</property> into the <property>employees.rptdesign</property>.</para> @@ -158,6 +173,7 @@ <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> + <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> @@ -177,10 +193,13 @@ 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> + </listitem> + <listitem> + <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 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> + <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>Resulted Dynamic Report</title> <mediaobject> @@ -189,5 +208,6 @@ </imageobject> </mediaobject> </figure> - + </listitem> +</orderedlist> </section>