Author: irooskov(a)redhat.com Date: 2010-12-09 17:16:49 -0500 (Thu, 09 Dec 2010) New Revision: 27301 Added: trunk/birt/docs/en-US/birt_integration_with_seam.xml trunk/birt/docs/en-US/birt_reports_deployment.xml trunk/birt/docs/en-US/framework.xml trunk/birt/docs/en-US/hibernate_datasource.xml trunk/birt/docs/en-US/introduction.xml trunk/birt/docs/en-US/links.xml trunk/birt/docs/en-US/tasks.xml trunk/birt/docs/publican.cfg Log: added back files Added: trunk/birt/docs/en-US/birt_integration_with_seam.xml =================================================================== --- trunk/birt/docs/en-US/birt_integration_with_seam.xml (rev 0) +++ trunk/birt/docs/en-US/birt_integration_with_seam.xml 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,255 @@ +<?xml version='1.0' encoding='UTF-8'?> +<section id="birt_integration_with_seam"> + <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>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> + + <tip> + <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> + </tip> + + <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> + + <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> + <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 + and enable the <emphasis> + <property>Birt Reporting Runtime Component</property> + </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> + <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> + + + <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. + </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> + </listitem> + </orderedlist> + </section> + + <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. + 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> + 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> + 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. 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[ + 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> + + </listitem> + + + + + <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> + + <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> + </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> +</section> \ No newline at end of file Added: trunk/birt/docs/en-US/birt_reports_deployment.xml =================================================================== --- trunk/birt/docs/en-US/birt_reports_deployment.xml (rev 0) +++ trunk/birt/docs/en-US/birt_reports_deployment.xml 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,220 @@ +<?xml version='1.0' encoding='UTF-8'?> +<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> + + + <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> + + + 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 + +]]></programlisting> + </listitem> + <listitem> + <para>Make a table in the report and put each data set item into a column.</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[ +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> + </listitem> + <listitem> +<para>The report is ready. You can preview it to make sure it works properly. </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[ +<!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> + </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> + +<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> + + <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> + </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> + + </para> + <figure> + <title>Dynamic Report</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/birt_reports_deployment/productReport.png"/> + </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 + don&apos;t specify the JNDI URL property, our engine will try the following JNDI + URLs:</para> + <itemizedlist> + <listitem> + <para> + <emphasis>java:/&lt;project_name&gt;</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>java:/&lt;project_name&gt;EntityManagerFactory</emphasis> + </para> + </listitem> + </itemizedlist> + + <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 + 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 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> + + <programlisting role="XHTML"><![CDATA[<property name="hibernate.session_factory_name" value="java:/projectname"/> + ]]></programlisting> + + <para>And you can use <emphasis>java:/projectname</emphasis> as the JNDI URL property when creating a BIRT + Hibernate Data Source.</para> + + <note> + <title>Note:</title> + <para>If you want to test this feature using PDE Runtime, you need to add <emphasis> + <property>osgi.dev=bin</property> + </emphasis> to the <emphasis> + <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 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&... + Tools Forum</ulink>. You can also influence on how you want to see JBoss Tools docs in + 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> + +</section> Added: trunk/birt/docs/en-US/framework.xml =================================================================== --- trunk/birt/docs/en-US/framework.xml (rev 0) +++ trunk/birt/docs/en-US/framework.xml 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,260 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="framework"> + <?dbhtml filename="framework.html"?> + + <chapterinfo> + <keywordset> + + <keyword>Eclipse</keyword> + <keyword>JBoss</keyword> + <keyword>JBoss Tools</keyword> + <keyword>BIRT Integration</keyword> + </keywordset> + </chapterinfo> + + <title>JBoss BIRT Integraion Framework API Reference</title> + + +<section> + + <title> + <emphasis role="bold"> <property>&lt;b:birt&gt;</property></emphasis> Component + </title> + + + +<para> + The <emphasis role="bold"> <property>&lt;b:birt&gt;</property></emphasis> component servers to integrate a BIRT report into Seam/JSF container. + The <emphasis role="bold"> <property>&lt;b:birt&gt;</property></emphasis> tag recognizes most of the parameters described on the BIRT + <ulink url="http://www.eclipse.org/birt/phoenix/deploy/viewerUsage2.2.php#p... Viewer Parameters</ulink> page, though it has attributes of its own. + +</para> + + + <table> + <title><emphasis role="bold"> <property>&lt;b:birt&gt;</property></emphasis> Component Reference</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Attribute</entry> + <entry>Correspondance to BIRT Report Viewer parameters</entry> + <entry>Description/</entry> + + </row> + </thead> + <tbody> + <row> + <entry>designType</entry> + <entry> - </entry> + <entry>Corresponds to the BIRT servlet mappings. Possible values are run, frameset, preview and embed. + If the attribute is set to embed the component is used for + embeddable html. This type ignores all the attributes except designName + and masterpage. + </entry> + </row> + <row> + <entry>embeddable</entry> + <entry> - </entry> + <entry>A BIRT report occupies the whole page by default. It contains the &lt;html&gt;, + &lt;head&gt;, &lt;body&gt; etc., tags. Embedded report can be a part of another page. + It doesn't contain the above mentioned tags. Only HTML report can be embedded.</entry> + </row> + <row> + <entry>designName</entry> + <entry>__report</entry> + <entry>Sets the name of the report design to process. This can be an absolute path or relative to the working folder. Valid values are run, frameset and preview</entry> + </row> + + <row> + <entry>format</entry> + <entry>__format</entry> + <entry>Specifies the desired output format, such as pdf, html, doc, ppt, or xls.</entry> + </row> + + <row> + <entry>title</entry> + <entry>__title</entry> + <entry>Sets the report title.</entry> + </row> + + <row> + <entry>showtitle</entry> + <entry>__showtitle</entry> + <entry>Determines if the report title is shown in the frameset viewer. Defaults to true.</entry> + </row> + + <row> + <entry>toolbar</entry> + <entry>__toolbar</entry> + <entry> + + Determines if the report toolbar is shown in the frameset viewer.Defaults to true. Valid values are true and false.</entry> + </row> + + + + <row> + <entry>navigationbar</entry> + <entry>__navigationbar</entry> + <entry> + + Determines if the navigation bar is shown in the frameset viewer. Defaults to true. Valid values are true and false.</entry> + </row> + + + <row> + <entry>document</entry> + <entry>__document</entry> + <entry> + Sets the name for the rptdocument. The document is created when the report engine separates run and render tasks, and + is used to support features like table of contents and pagination. + This setting can be an absolute path or relative to the working folder. If no document parameter is used, a unique document is created in the document folder. + </entry> + </row> + + <row> + <entry>locale</entry> + <entry>__locale</entry> + <entry> + Specifies the locale for the specific operation. Note that this will override the default locale. + </entry> + </row> + <row> + <entry>svg</entry> + <entry>__svg</entry> + <entry> + Specifies whether SVG is supported. + </entry> + </row> + + + + <row> + <entry>page</entry> + <entry>__page</entry> + <entry> + Specifies specific page to render. + </entry> + </row> + + + <row> + <entry>pagerange</entry> + <entry>__pagerange</entry> + <entry> + Specifies page range to render. Eg 1-4,7. + </entry> + </row> + + + <row> + <entry>masterpage</entry> + <entry>__masterpage</entry> + <entry> + + Indicates that the report master page should be used or not. Validvalues are true and false. + </entry> + </row> + + + <row> + <entry>overwrite</entry> + <entry>__overwrite</entry> + <entry> + + This setting if set to true will force an overwrite of the existing report document. + </entry> + </row> + + <row> + <entry>bookmark</entry> + <entry>__bookmark</entry> + <entry> + + Specifies a specific bookmark within the report to load. The viewer will automatically load the appropriate page. + </entry> + </row> + + + + <row> + <entry>rtl</entry> + <entry>__rtl</entry> + <entry> + Specifies whether to display the report in right to left format. This setting defaults to false. + </entry> + </row> + + + + <row> + <entry>fittopage</entry> + <entry>__fittopage</entry> + <entry> + Specifies whether PDF generation should fit content to a page. Valid values are true and false. + </entry> + </row> + + + <row> + <entry>resourceFolder</entry> + <entry>__resourceFolder</entry> + <entry> + Specifies the resource folder to use. This setting will override the default setting in the web.xml. The resource folder is used to locate libraries, images, and resource files. + </entry> + </row> + + </tbody> + </tgroup> + </table> + +</section> + + <section> + <title><emphasis role="bold"> <property>&lt;b:param&gt;</property></emphasis> Component</title> + <para> + The <emphasis role="bold"> <property>&lt;b:param&gt;</property></emphasis> tag describes report parameter. + </para> + + <table> + <title><emphasis role="bold"> <property>&lt;b:param&gt;</property></emphasis> Component</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Attribute</entry> + + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>name</entry> + <entry>The parameter name. Required.</entry> + </row> + <row> + <entry>value</entry> + <entry>The parameter value. Required.</entry> + </row> + + <row> + <entry>isnull</entry> + <entry>Specifies that a report parameter has a null value</entry> + </row> + <row> + <entry>islocale</entry> + <entry>Specifies whether the parameter is localized</entry> + </row> + + </tbody> + + </tgroup> + </table> + </section> + + + + + + + +</chapter> Added: trunk/birt/docs/en-US/hibernate_datasource.xml =================================================================== --- trunk/birt/docs/en-US/hibernate_datasource.xml (rev 0) +++ trunk/birt/docs/en-US/hibernate_datasource.xml 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,213 @@ +<?xml version='1.0' encoding='UTF-8'?> +<section id="hibernate_datasource"> + + + <title>Using Hibernate ODA Data Source</title> + + <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 + Entities please read <ulink + url="http://download.jboss.org/jbosstools/nightly-docs/en/seam/html_... + >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> + <para>Before performing Seam Generate Entities, you should have a connection profile + 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_... + >CRUD Database Application</ulink> chapter of the Seam Dev Tools Reference + guide.</para> + <para> + If you followed the steps described in the + <link linkend="birt_integration_with_seam">Adding BIRT Functionality to Standard Seam Web Project</link> chapter, + 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> + <property>New Data Source</property>.</emphasis></para> + + <figure> + <title>Creating a New Data Source</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_datasource/creatingDataSource.png"/> + </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> + <property>HibernateDataSource</property> + </emphasis>. Hit <emphasis> + <property>Next</property> to proceed.</emphasis></para> + + <figure> + <title>Creating Hibernate Data Source</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_datasource/hibernateDataSource.png"/> + </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> + + <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> + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_datasource/connectionSuccessful.png"/> + </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> + <property>Data Set</property> + </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> + + + + + <figure> + <title>Creating a Hibernate ODA Data Set</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_datasource/addingHibernateODADataset.png"/> + </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> + + <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 facilitate query composing.</para> + + <figure> + <title>Composing query for Data Set</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_datasource/testingQuery.png"/> + </imageobject> + </mediaobject> + </figure> + </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> + + + <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> + + +<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> + </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 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> + <imageobject> + <imagedata fileref="images/hibernate_datasource/finalReport.png"/> + </imageobject> + </mediaobject> + </figure> + </listitem> +</orderedlist> +</section> Added: trunk/birt/docs/en-US/introduction.xml =================================================================== --- trunk/birt/docs/en-US/introduction.xml (rev 0) +++ trunk/birt/docs/en-US/introduction.xml 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="introduction"> + <?dbhtml filename="introduction.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>JBoss</keyword> + <keyword>JBoss Tools</keyword> + <keyword>JBDS</keyword> + <keyword>BIRT Plugin</keyword> + </keywordset> + </chapterinfo> + + <title>Introduction</title> + + + + + <section> + + <title>What is BIRT?</title> + <para>BIRT plugin is an Eclipse-based open source reporting system for web applications + based on Java and J2EE. BIRT consists of two main components: a report designer based on + Eclipse, and a runtime component that can be added to your app server. BIRT also offers + a charting engine that lets you add charts to your own Web application.</para> + <para>With the help of BIRT you can generate a great number of reports to be used in your + application:</para> + + <itemizedlist> + <listitem> + <para>Lists</para> + </listitem> + <listitem> + <para>Charts</para> + </listitem> + <listitem> + <para>Crosstabs, or cross-tabulation, or matrix</para> + </listitem> + <listitem> + <para>Letters and Documents</para> + </listitem> + <listitem> + <para>Compound Reports</para> + </listitem> + </itemizedlist> + + <para>You can find more detailed information on the BIRT plugin, its report types and + anatomy on the <ulink url="http://www.eclipse.org/birt/phoenix/intro/">BIRT Homepage</ulink>.</para> + + <para>To understand the basic BIRT concepts and to know how to create a basic BIRT report, + refer to the <ulink url="http://www.eclipse.org/birt/phoenix/tutorial/">Eclipse BIRT + Tutorials</ulink>. What extensions <property>JBoss Tools</property> provides for + Eclipse BIRT you&apos;ll find out in the next sections.</para> + </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> + 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 <!--<ulink + url="&gsglink;#JBossToolsInstall" + >-->JBoss Tools Installation<!--</ulink>--> section)</para> + </listitem> + <listitem> + <para>BIRT Report Designer (BIRT Report Designer 2.3.2 + you can download from <ulink + url="http://www.eclipse.org/downloads/download.php?file=/birt/downlo... + >Eclipse downloads site</ulink>)</para> + </listitem> + <listitem> + <para>BIRT Web Tools Integration ( BIRT WTP Integration 2.3.2 you can download from + <ulink + url="http://www.eclipse.org/downloads/download.php?file=/birt/downlo... + >Eclipse downloads site</ulink>)</para> + </listitem> + </itemizedlist> + + <note> + <title>Note:</title> + <para>Versions of BIRT framework and BIRT WTP integration should be no less than RC4 in + order to the BIRT facet works correctly.</para> + </note> + </section> + + + +</chapter> Added: trunk/birt/docs/en-US/links.xml =================================================================== --- trunk/birt/docs/en-US/links.xml (rev 0) +++ trunk/birt/docs/en-US/links.xml 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,23 @@ +<?xml version='1.0' encoding='UTF-8'?> + +<chapter id="birt_plugin_rel_resources" xreflabel="birt_plugin_rel_resources"> + <?dbhtml filename="links.html"?> + <chapterinfo> + <keywordset> + + <keyword>Eclipse</keyword> + <keyword>JBoss</keyword> + <keyword>JBoss Tools</keyword> + <keyword>BIRT Integration</keyword> + </keywordset> + </chapterinfo> + + + <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...;. + +</para> + +</chapter> Added: trunk/birt/docs/en-US/tasks.xml =================================================================== --- trunk/birt/docs/en-US/tasks.xml (rev 0) +++ trunk/birt/docs/en-US/tasks.xml 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,29 @@ +<?xml version='1.0' encoding='UTF-8'?> + +<chapter id="tasks" xreflabel="tasks"> + <?dbhtml filename="tasks.html"?> + <chapterinfo> + <keywordset> + + <keyword>Eclipse</keyword> + <keyword>JBoss</keyword> + <keyword>JBoss Tools</keyword> + <keyword>BIRT Integration</keyword> + </keywordset> + </chapterinfo> + + <title>Tasks</title> + <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> + + + + + <!-- &birt_integration_with_seam; + &hibernate_datasource; + &birt_reports_deployment; --> + <xi:include href="birt_integration_with_seam.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="hibernate_datasource.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="birt_reports_deployment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + +</chapter> Added: trunk/birt/docs/publican.cfg =================================================================== --- trunk/birt/docs/publican.cfg (rev 0) +++ trunk/birt/docs/publican.cfg 2010-12-09 22:16:49 UTC (rev 27301) @@ -0,0 +1,8 @@ +# Config::Simple 4.59 +# Fri Nov 27 08:57:18 2009 + +xml_lang: en-US +type: Book +brand: JBoss +debug: 1 +