XmlEngine user s manual 7 th April 2006 Revision 1.0 Visit us at www.openbravo.com
Table of Contents I.Introduction... 3 II.Requirements... 4 III.License... 5 IV.Installation... 6 V.System overview... 7 VI.Building XmlEngine from the sources... 11 VII.Example reports... 12 VII.1Example 1: Initial sample... 12 VII.2Example 2: Multiple queries... 15 VII.3Example 3: Sum and count functions... 16 VII.4Example 4: Defining the database driver and URL in the web.xml... 18 VII.5Example 5: Data grouping... 21 VII.6Example 6: Functions at different grouping levels... 23 VII.7Example 7: Using dynamic SQL queries... 25 VII.8Example 8: Using parameters... 27 VII.9Example 9: Changing attributes with parameters... 29 VII.10Example 10: Replacing a part of a value on an attribute... 31 VII.11Example 11: Using Boolean attributes... 33 VII.12Example 12: Creating subreports... 35 VII.13Example 13: More functions... 38 VII.14Example 14: the EQUAL function... 40 VII.15Example 15: Functions and fields format... 42 VIII.Application examples... 44 VIII.1Demo application without database... 44 VIII.2Demo application with a database connection... 49 XmlEngine_tutorial - Apr 7, 2006 2/51
I.Introduction I. Introduction XmlEngine is a tool that produces forms and reports according to templates defined in XML, including FOP (Formatting Objects Processor), or HTML mark-up languages. These templates combined with a configuration file define the design of forms and reports and let users to have full control of how the information is organized and displayed. XmlEngine can be used as part of other applications, as we do in Openbravo ERP, or as a servlet as in the examples included in this manual. XmlEngine produces highly customized reports and has advanced report features such as headers and footers, data grouping and data functions. XmlEngine_tutorial - Apr 7, 2006 3/51
II.Requirements II. Requirements Operating systems supported: Microsoft Windows XP, 2000 or 2003 server. Linux. It has been successfully tested in Red Hat and Fedora systems. To run XmlEngine, you need to install the following software: Jakarta-Tomcat version 5.5 or better. It can be downloaded from http://tomcat.apache.org/ Additionally, if you also plan to build applications you need to install this additional software: Java 2 Platform Enterprise Edition 1.5 SDK or better. It can be downloaded from http://java.sun.com/javaee/downloads/ Additionally, if you also plan to build XmlEngine from the sources you need to install this additional software: Apache-ant 1.5. It can be downloaded from http://ant.apache.org/ Operating systems supported: Microsoft Windows XP, 2000 or 2003 server. Linux. It has been successfully tested in Red Hat and Fedora systems. To run Openbravo, you need to install the following software: Jakarta-Tomcat version 5.5. It can be downloaded from http://tomcat.apache.org/ Java 2 Platform Standard Edition 5.0. It can be downloaded from http://java.sun.com/j2se/1.5.0/download.jsp Oracle 10g release 2. It can be downloaded from http://www.oracle.com Apache-ant 1.5. It can be downloaded from http://ant.apache.org/ XmlEngine_tutorial - Apr 7, 2006 4/51
III.License III. License The contents of this file are subject to the Openbravo Public License Version 1.0 (the "License"), being the Mozilla Public License version 1.1 with a permitted attribution clause; you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.openbravo.com/legal/license.html Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. The Original Code is Openbravo ERP. The Initial Developer of the Original Code is Openbravo SL All portions are Copyright (C) 2001-2006 Openbravo SL All Rights Reserved. XmlEngine_tutorial - Apr 7, 2006 5/51
IV.Installation IV. Installation This is a quick-start installation that explains how to install XmlEngine step by step: Make sure that you have installed all the required software from third parties (Tomcat) described in the requirements section of this document. Unzip the downloaded XmlEngine classes file and copy the files into your Tomcat directory. The examples can be executed using the following URL: webapps\xmlengine\example-urls.html that contains a list of URL to the different samples XmlEngine_tutorial - Apr 7, 2006 6/51
V.System overview V. System overview XmlEngine can work as a servlet. There are few examples in this manual that describe in detail its features and possibilities when running in this mode of operation. The following table shows the output generated by a sample using XmlEngine as a servlet. Screen capture of an XmlEngine used as a servlet Hours of labour Employee Year Month Day Hours Johann 2002 4 1 7 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 XmlEngine can also be integrated in external applications. In this scenario, it receives the input parameters from the application (such as a configuration file parameter) and returns an output string. It uses a configuration file and a template, but instead of building an SQL query, the data is taken from the application. Screen capture of an XmlEngine used by an external application XmlEngine_tutorial - Apr 7, 2006 7/51
V.System overview Screen capture of an XmlEngine generated report XmlEngine needs two files to generate reports: An HTML/XML template file that contains the visual representation of how the data is displayed. An XML configuration file that contains the parameters needed to process the template correctly. The template can be created using any HTML editor, so the designer can work using a WYSIWYG (What You See Is What You Get) and see how the document looks instead of editing complex template files. This is a simple XML configuration file: <?xml version="1.0"?> <REPORT> <template file="example01.html" /> <structure name="structure1"> <CONNECTION driver = "org.apache.derby.jdbc.embeddeddriver" URL = "jdbc:derby:../webapps/xmlengine/web- INF/database/tutorialDB"/> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <SECTION id="sectiondetail"/> </structure> <DISCARD id="example"/> </REPORT> XmlEngine_tutorial - Apr 7, 2006 8/51
V.System overview These are some of tags commonly used in XmlEngine configuration files: The <report> tag indicates that the block that is going to be defined is a report definition. The <template> tag indicates through the file attribute which is the name of the template file that is used for this configuration file. The <connection> tag describes how the connection to the database is performed. The driver attribute indicates which database driver is used and the url attribute indicates the location of the database. This connection details can be also specified in the server configuration file. The <sql> tag indicates the SQL query that needs to be performed to get the data from the database. The <field> tag describes the mapping between the database fields and the templates are done. There are also some common tips and rules for creating XML configuration and HTML/XML template files: You can use the HTML <span> tag to place an id if there is no previous element to place it. The id attribute values on the document must be unique, so each element can be identified correctly. XmlEngine_tutorial - Apr 7, 2006 9/51
VI.Building XmlEngine from the sources VI. Building XmlEngine from the sources To build XmlEngine from the sources, we need to compile the Java sources and move to the compiled Java classes to the XmlEngine Tomcat s context directory. A build.xml file for Ant is provided with the source distribution. Before executing Ant, check the initial parameters on the build.xml file are the correct for you configuration. XmlEngine_tutorial - Apr 7, 2006 10/51
VII. Example reports In the following pages we are going to introduce some samples that show how to use XmlEngine as servlet and in an application. The examples have been developed using Derby database but they can be modified to use any database that has a JDBC driver. VII.1 Example 1: Initial sample In this first sample, we use a simple query to obtain a table that contains the hours worked by a group of different employees. Output of m example 1 Hours of labour Employee Year Month Day Hours Johann 2002 4 1 7 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 Template file: example01.html <html> <head> <title>hours of labour</title> <META http-equiv="content-type" content="text/html" charset=iso-8859-1"> </head> <body bgcolor="#ffffff" text="#000000"> <h1 align="center">hours of labour</h1> <table width="75%" border="1" align="center"> <tr> <td>employee</td> <td>year</td> <td>month</td> <td>day</td> <td>hours</td> </tr> <div class="sectiondetail"> XmlEngine_tutorial - Apr 7, 2006 11/51
<tr> <td id="fieldemployee">xfrank</td> <td id="fieldyear">x2002</td> <td id="fieldmonth">x02</td> <td id="fieldday">x1</td> <td id="fieldhours">x8</td> </tr> </div> <div class="example"> <tr> <td>xjohann</td> <td>x2002</td> <td>x03</td> <td>x2</td> <td>x6</td> </tr> <tr> <td>xalfred</td> <td>x2002</td> <td>x03</td> <td>x4</td> <td>x8</td> </tr> </div> </table> </body> </html> Configuration file: example01.xml <?xml version="1.0"?> <REPORT> <template file="example01.html" /> <structure name="structure1"> <CONNECTION driver = "org.apache.derby.jdbc.embeddeddriver" URL = "jdbc:derby:../webapps/xmlengine/web- INF/database/tutorialDB"/> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> XmlEngine_tutorial - Apr 7, 2006 12/51
<FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <SECTION id="sectiondetail"/> </structure> <DISCARD id="example"/> </REPORT> In this example, the SQL sentence contained between <sql> tags obtains all the records of the Hours table: <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> The mapping between fields and columns is described by the field tag as follows: <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> The first line indicates that the Employee column will we displayed in the field with id fieldemployee. The SQL query can return any number of records. For each one, the code of the template that is inside the <div> tag has the same identifier than the <section> tag of the configuration file. <SECTION id="sectiondetail"/> If there are more detail datas in the template than the strictly need these can be ignored from final result using the <discard> tag in the configuration file. <DISCARD id="example"/> This tag indicates that all lines in the template which are between tags with the same id of the <discard> tag are ignored. VII.2 Example 2: Multiple queries This example shows how multiple queries can be integrated in a single output document. XmlEngine_tutorial - Apr 7, 2006 13/51
Output of example 2 Hours of labour Employee Year Month Day Hours Johann 2002 4 1 7 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 Configuration file: example02.xml <?xml version="1.0"?> <REPORT> <template file="example02.html" /> <structure name="structure1"> <CONNECTION driver = "org.apache.derby.jdbc.embeddeddriver" URL = "jdbc:derby:../webapps/xmlengine/web- INF/database/tutorialDB"/> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <SECTION id="sectiondetail"/> </structure> <structure name="structure2"> <CONNECTION driver = "org.apache.derby.jdbc.embeddeddriver" URL = "jdbc:derby:../webapps/xmlengine/web- INF/database/tutorialDB"/> <SQL> XmlEngine_tutorial - Apr 7, 2006 14/51
SELECT distinct Employee FROM Hours </SQL> <FIELD id="fieldemployee2">employee</field> <SECTION id="sectiondetailemployee"/> </structure> <DISCARD id="example"/> </REPORT> Each query is contained between a <structure> tag and can be performed on different databases. On the HTML/XML template document, there is a list of employees that refer to the elements of the new structure. Template file: example02.html <center> <h2>employees</h2> <ul> <div class="sectiondetailemployee"> <li id="fieldemployee2">xfrank</li> </ul> </center> VII.3 Example 3: Sum and count functions This example shows how sum and count functions work. Output of example 3 Hours of labour - 6 parts Employee Year Month Day Hours Johann 2002 4 1 7 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 Total 38.0 Configuration file: example03.xml <?xml version="1.0"?> <REPORT> <template file="example03.html" /> XmlEngine_tutorial - Apr 7, 2006 15/51
<structure name="structure1"> <CONNECTION driver = "org.apache.derby.jdbc.embeddeddriver" URL = "jdbc:derby:../webapps/xmlengine/web- INF/database/tutorialDB"/> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> </structure> <structure name="structure2"> <CONNECTION driver = "org.apache.derby.jdbc.embeddeddriver" URL = "jdbc:derby:../webapps/xmlengine/web- INF/database/tutorialDB"/> <SQL> SELECT distinct Employee FROM Hours </SQL> <FIELD id="fieldemployee2">employee</field> <SECTION id="sectiondetailemployee"/> </structure> <DISCARD id="example"/> </REPORT> XmlEngine_tutorial - Apr 7, 2006 16/51
In this example, we use the SUM and COUNT functions to perform operations on data retrieved from the database and include the results in the report. To use this kind of functionality, we use the <function> tag as shown below: <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> You can get also an average value instead of a sum using the MED function: <FUNCTION id="funcmedhours" name="med">hours</function> VII.4 Example 4: Defining the database driver and URL in the web.xml This example shows how to use define the driver and URL used to connect to the database in the initializing parameters of the XmlEngine servlet. Output of example 4 Hours of labour - 6 parts Employee Year Month Day Hours Johann 2002 4 1 7 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 Total 38.0 The default database connection parameters can be setup in the web.xml file. For example, to indicate that we want to use the driver org.apache.derby.jdbc.embeddeddriver and the URL of the database is jdbc:derby:../webapps/xmlengine/web-inf/database/tutorialdb we add the following lines to the web.xml configuration file: <init-param> <param-name>driver</param-name> <paramvalue>org.apache.derby.jdbc.embeddeddriver</param -value> </init-param> XmlEngine_tutorial - Apr 7, 2006 17/51
<init-param> <param-name>url</param-name> <param- value>jdbc:derby:../webapps/xmlengine/web- INF/database/tutorialDB</param-value> </init-param> Using this approach, there is no need to specify the connection details in our servlets. The following example uses the connection details specified in web.xml to perform the connection. Configuration file: Example04.xml <?xml version="1.0"?> <REPORT> <template file="list4.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> </structure> </REPORT> Template file: example04.html <html> <head> <title>hours of labour</title> <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> XmlEngine_tutorial - Apr 7, 2006 18/51
</head> <body bgcolor="#ffffff" text="#000000"> <h1 align="center">hours of labour - <span id="funccountparts">xx2</span> parts</h1> <table width="75%" border="1" align="center"> <tr> <td>employee</td> <td>year</td> <td>month</td> <td>day</td> <td>hours</td> </tr> <div class="sectiondetail"> <tr> <td id="fieldemployee">xfrank</td> <td id="fieldyear">x2002</td&g; <td id="fieldmonth">x02</td> <td id="fieldday">x1</td> <td id="fieldhours">x8</td> </tr> </div> <tr> <td>total</td> <td colspan="4" id="funcsumhours" align="right">x34</td> </tr> </table> </body> </html> VII.5 Example 5: Data grouping This example shows how to use data grouping in our output reports allow grouping by different criteria. Output of example 5 Hours of labour - 6 parts Year: 2001 Month: 12 Employee Year Month Day Hours XmlEngine_tutorial - Apr 7, 2006 19/51
Peter 2001 12 26 5 Total 5.0 Year: 2002 Month: 4 Employee Year Month Day Hours Peter 2002 4 14 7 Johann 2002 4 1 7 Total 14.0 Month: 5 Employee Year Month Day Hours Peter 2002 5 15 3 Peter 2002 5 2 8 Johann 2002 5 15 8 Total On the previous documents, there was just a section in the XML configuration file called sectiondetail. This section was repeated for each data record on the query. However, it is possible to have more than a section on a structure. The field attribute on the <section> tag indicates how the data is grouped. Notice from the output of this example that the sum function is now applied to each month. Configuration file: Example05.xml <?xml version="1.0"?> <REPORT> <template file="example05.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours ORDER BY ReportYear, ReportMonth </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> XmlEngine_tutorial - Apr 7, 2006 20/51
<FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectionyear" field="reportyear"/> <SECTION id="sectionmonth" field="reportmonth"/> <SECTION id="sectiondetail"/> </structure> </REPORT> VII.6 Example 6: Functions at different grouping levels Total year: 5.0 This example shows how to combine functions and grouping. It computes a result per every year and then sums the results of all years. Total year: 33.0 Output of example 6 Hours of labour - 6 parts Year: 2001 Month: 12 Employee Year Month Day Hours Peter 2001 12 26 5 Total 5.0 Year: 2002 Month: 4 Employee Year Month Day Hours Peter 2002 4 14 7 Johann 2002 4 1 7 Total 14.0 Month: 5 XmlEngine_tutorial - Apr 7, 2006 21/51
Total general: 38.0 Employee Year Month Day Hours Peter 2002 5 15 3 Peter 2002 5 2 8 Johann 2002 5 15 8 Total 19.0 Configuration file: Example06.xml <?xml version="1.0"?> <REPORT> <template file="example06.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours ORDER BY ReportYear, ReportMonth </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <FUNCTION id="funcsumhoursyear" name="sum">hours</function> <FUNCTION id="funcsumhourstotal" name="sum">hours</function> <SECTION id="sectionyear" field= ReportYear /> <SECTION id="sectionmonth" field= ReportMonth /> <SECTION id="sectiondetail"/> </structure> </REPORT> XmlEngine_tutorial - Apr 7, 2006 22/51
In the example 5 there was only a sum function. In this new example, there are two sum functions at different levels of the structure. Those operations perform sums per year and generate a total result. To include a sum per year it is necessary to define a new function in the XML configuration file: <FUNCTION id="funcsumhoursyear" name="sum">hours</function> In the template we have to include the id of this new sum between the blocks that enclose the <div> tags of the sections sectionmonth and sectionyear. <div class="sectionyear"> <h2 align="center">year: <span id="fieldyear">x2000</span><h2> Total year: <span id="funcsumhoursyear">xx10</span> <div id="sectionmonth"> If a general total result is also need it, we just need to insert another sum function in the XML configuration file: <FUNCTION id="funcsumhourstotal" name="sum">hours</function> The id of this sum must be placed out of the <div> tag of the sectionyear. In the HTML/XML template, the following line needs to be added: <h3>total general: <span id="funcsumhourstotal">xx10</span></h3> In the HTML file, the id is placed in a new <span> tag because there is no previous element that can be use to include it. VII.7 Example 7: Using dynamic SQL queries Total year: 5.0 This example shows how to use dynamic SQL queries. Until now the SQL queries that we used were static. XmlEngine can also work with dynamic SQL queries. This can be archived adding the argument name and its values to the URL address. Output of example 7 Hours of labour - 1 parts Year: 2001 Month: 12 XmlEngine_tutorial - Apr 7, 2006 23/51
Total general: 5.0 Employee Year Month Day Hours Peter 2001 12 26 5 Total 5.0 Configuration file: Example07.xml <?xml version="1.0"?> <REPORT> <template file="example07.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours WHERE Year=? ORDER BY ReportYear, ReportMonth </SQL> <PARAMETER_SQL name = "year" type = "string" default = "2000" /> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <FUNCTION id="funcsumhoursyear" name="sum">hours</function> <FUNCTION id="funcsumhourstotal" name="sum">hours</function> <SECTION id="sectionyear" field= ReportYear /> <SECTION id="sectionmonth" field= ReportMonth /> <SECTION id="sectiondetail"/> </structure> </REPORT> In the previous sample, we had the following XML configuration file: <SQL> XmlEngine_tutorial - Apr 7, 2006 24/51
SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours WHERE Year=? ORDER BY ReportYear, ReportMonth </SQL> <PARAMETER_SQL name = "year" type = "string" default = "2000" /> <FIELD id="fieldemployee">employee</field> The <parameter_sql> defines dynamic SQL parameters. It accepts the following parameters: name: indicates the parameter on the query (as appears in the URL). type: the argument type: string or integer. default: the default value of the parameter in case it is not defined in the URL. For example: <PARAMETER_SQL name = "year" type = "string" default = "2000" /> The URL without arguments: http://localhost:8080/xmlengine/ XmlEngine.html?report=examples\example07 Returns no results in the output because the default value 2000 is used and there is no data for this year. However, if we use this URL: http://localhost:8080/xmlengine/xmlengine.html? report=examples\example07&year=2001 It will correctly report the year 2001 report. VII.8 Example 8: Using parameters This example shows how to use parameters in a generated report from an URL. Output of example 8 Hours of labour - 6 parts Print Date: 02-02-2005 Employee Year Month Day Hours XmlEngine_tutorial - Apr 7, 2006 25/51
Johann 2002 4 1 7 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 Total 38.0 Configuration file: Example08.xml <?xml version="1.0"?> <REPORT> <template file="example08.html" /> <PARAMETER id="param1" name = "date" default=" "/> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> </structure> </REPORT> It is possible to introduce a parameter on a report from an URL. It works as a parameter in the XML document and as a field in the HTML document, as in the other examples. Using <parameter> tag, the supported attributes are: id: identifies the place on the template where it will be shown name: Identifies the parameter on the query, it will appear on the URL. default: the default value of the parameter in case is not defined in the URL. XmlEngine_tutorial - Apr 7, 2006 26/51
As we can see in this example template: <PARAMETER id= param1 name = "date" default=" "/> The default value for this parameter is "". The destination where the parameter will be written is indicated in the HTML document. We can invoke this example with this URL: http://localhost:8080/xmlengine/xmlengine.html? report=examples\example08&date=06-02-2002 VII.9 Example 9: Changing attributes with parameters This example shows how to use change the value of an attribute using parameters. Output of example 9 Hours of labour - 6 parts Print Date: 02-02-2005 Employee Year Month Day Hours Johann 2002 4 1 7 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 Total 38.0 Configuration file: Example09.xml <?xml version="1.0"?> <REPORT> <template file="example09.html" /> <PARAMETER id="param1" name = "date" default=" "/> <PARAMETER id="funcsumhours" name = "cols" attribute="colspan"/> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours XmlEngine_tutorial - Apr 7, 2006 27/51
</SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> </structure> </REPORT> In previous examples we have seen how to change the tag value in the HTML document using <field>, <function> and <parameter> tags. Now, we are going to see how to change the value of an attribute. As example, we are going to use a parameter to indicate the number of columns that will be used in the total result cell. Currently, the line looks like: <td colspan="4" id="funcsumhours" align="right">x34</td> To change the colspan attribute using a parameter we add the following file in the XML configuration file: <PARAMETER id="funcsumhours" name = "cols" attribute="colspan"/> The name attribute is the name of the parameter that we have to include in the URL. To invoke the servlet, we use the following URL with the argument cols set to value 2: http://localhost:8080/xmlengine/ XmlEngine.html? report=examples\example09&date=06-02- 2002&cols=2 We can see that the cell where the total is now only takes 2 columns. In this example it we have used the <parameter> tag but the same functionality is available in the <field> and <function> tags. XmlEngine_tutorial - Apr 7, 2006 28/51
VII.10 Example 10: Replacing a part of a value on an attribute This example shows how to replace a part of a value on an attribute of an HTML tag. Output of example 10 Hours of labour - 6 parts Employee Year Month Day Hours Personal page Johann 2002 4 1 7 Personal page Johann 2002 5 15 8 Personal page Peter 2001 12 26 5 Personal page Peter 2002 4 14 7 Personal page Peter 2002 5 2 8 Personal page Peter 2002 5 15 3 Total 38.0 Sometimes there is the need to change the values of attributes. For example, to update a hyperlink. The following example is based on example4 and introduces a hyperlink that includes the employer name. We have to add another column to the table structure in the HTML document. Configuration file: Example10.xml <?xml version="1.0"?> <REPORT> <template file="example10.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldpageemployee" attribute="href" replace="yy">employee</field> <FIELD id="fieldyear">reportreportyear</field> <FIELD id="fieldmonth">reportreportmonth</field> <FIELD id="fieldday">reportreportday</field> <FIELD id="fieldhours">hours</field> XmlEngine_tutorial - Apr 7, 2006 29/51
<FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> </structure> </REPORT> We add another column in the HTML/XML template document where the employee link is displayed: <td><a id="fieldpageemployee" href="xmlengine?report=examples/list12sub&employe e=yy">personal page</a></td> If nothing else is changed, the output will have as many rows as the data record has but all of them with the same hyperlink argument: code=yy. It is necessary to change the hyperlink argument, using the replace= yy attribute. Using this method, we have changed part of an attribute on the hyperlink tag, but we maintain another part. Change example10.xml near <field> to the following: <FIELD id="fieldpageemployee" attribute="href"replace="yy">employee</field> This line indicates that on each line, yy must be remplaced by the employee value where id= fieldpageemployee if yy is part of <href> tag attribute. We can invoke the example with the following URL: http://localhost:8080/xmlengine/ XmlEngine.html?report=examples\example10 If we click on the link we will obtain another page with the total hours worked by the employee. VII.11 Example 11: Using Boolean attributes This example shows how to use boolean attributes in reports. Output of example 11 Hours of labour - 6 parts Check Employee Year Month Day Hours Johann 2002 4 1 7 XmlEngine_tutorial - Apr 7, 2006 30/51
Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Peter 2002 5 2 8 Peter 2002 5 15 3 Total 38.0 Configuration file: Example11.xml <?xml version="1.0"?> <REPORT> <template file="example11.html" /> <PARAMETER id="paramyear" name = "checkyear" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldcheckyear" boolean="checked" ithid="paramyear">reportyear</field> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> </structure> </REPORT> Unlike in HTML, XML requires a value for each attribute. For example, CheckOption only has an attribute when is checked but it does not when is not checked. We can indicate when a boolean attribute is true or not on the output using <field>, <function> and <parameter> tags. These tags accept the following attributes: attribute: identifies the attribute of the template. boolean: indicates the name of the attribute that will work as a boolean. XmlEngine_tutorial - Apr 7, 2006 31/51
withid: The boolean attribute is only shown if both the attribute and the withid value match. Take the example 4. Imagine that we need to include a new column with a checkbox field and we only want to check the values that match with the year indicated on the URL. We will need to add the following line: <td> <input id="fieldcheckyear" type="checkbox" name="checkbox" value="checkbox" checked></td> We now have a new column with checkoptions. We can check the values from a specific year including a <parameter> tag in HTML/XML template file like follows: <PARAMETER id="paramyear" name = "checkyear" /> This allows the servlet to receive the checkyear argument from the URL. Now, we add the <field> elements: <FIELD id="fieldcheckyear" boolean="checked" withid="paramyear"> Year </FIELD> We can invoke the example with the following URL: http://localhost:8080/xmlengine/ XmlEngine.html? report=examples\example11&checkyear=2001 The output shows as checked all the records from 2001. VII.12 Example 12: Creating subreports This example shows how to create subreports in a report. Output of example 12 Hours of labour - 6 parts Employee Year Month Day Hours Total Johann 2002 4 1 7 Total hours 15.0 Johann 2002 5 15 8 Peter 2001 12 26 5 Peter 2002 4 14 7 Total hours Total hours Total hours 15.0 23.0 23.0 XmlEngine_tutorial - Apr 7, 2006 32/51
Peter 2002 5 2 8 Total hours 23.0 Peter 2002 5 15 3 Total 38.0 Total hours 23.0 In some XML documents we may need to insert another report in the XML document. It can be independent from the main report. Configuration file: Example12.xml <?xml version="1.0"?> <REPORT> <template file="example12.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> <SUBREPORT id="reporttotalemployee" name="manual\list12sub" report="manual\list12sub"> <ARGUMENT name = "employee" withid="fieldemployee"/> </SUBREPORT> </structure> </REPORT> XmlEngine_tutorial - Apr 7, 2006 33/51
We are going to take the example 4 as a starting point and add an additional column that shows a subreport with the hours worked by that employee. The subreport is contained in the files list12sub.xml and list12sub.srpt. To invoke the servlet we use the following URL: http://localhost:8080/xmlengine/xmlengine.html?re port=examples\example2sub&employee=peter And we obtain the following result: Total hours 23.0 In configuration file we add the next lines at the same level than <field>, <function> or <section> tags: <SUBREPORT id="reporttotalemployee" name="examples\example12sub" report="examples\example12sub"> <ARGUMENT name = "employee" withid="fieldemployee"/> </SUBREPORT> As you can see, we have inserted the <subreport> tag that accepts the following attributes: id: identifies the place on the template where it will be shown name: Identifies the parameter on the query, it will appear on the URL. report: the name of the file where is the subreport, the same way it is used in the URL call. The <argument> tag sends arguments to the subreport. In the subreport, we receive the <parameter> or <parameter_sql> tags. The <argument> tag accepts the following attributes: name: identifies the argument in the subreport; a parameter with the same name must exist in the report. withid: indicates where the value is obtained. The change in the HTML template file is the same than for the tags that replace a value (<field>, <function> or <parameter>). In this case a new column in the table is inserted adding at the end of the first table row the following line: <td>total</td> and at the end of the second table row the line: <td id="reporttotalemployee">xtotal</td> Notice that the value of this id is the same than that the id attribute of <subreport> tag in the configuration file. The same way that we have send a value XmlEngine_tutorial - Apr 7, 2006 34/51
for a SQL parameter, it can be sent various parameters or receive the data in parameters just to show them. Subreport configuration file: example12sub.xml <?xml version="1.0"?> <REPORT> <template file="list12sub.srpt" /> <structure name="structure1"> <SQL> SELECT Sum(Hours) as sumhours FROM Hours WHERE Employee =? </SQL> <PARAMETER_SQL name = "employee" type = "string" default=" "/> <FIELD id="fieldhours">sumhours</field> <SECTION id="sectiondetail"/> </structure> </REPORT> Subreport template file: example12sub.srpt <table width="75%" border="1" align="center"> <tr> <td>total hours</td> <div class="sectiondetail"> <td id="fieldhours">x8</td> </div> </tr> </table> VII.13 Example 13: More functions This example shows how to use some additional functions. Output of example 13 Hours of labour - 6 parts Employee Year Month Day Month/Day Hours Minutes Johann 2002 4 1 4.0 7 420.0 Johann 2002 5 15 0.3333333333333333 8 480.0 Peter 2001 12 26 0.46153846153846156 5 300.0 Peter 2002 4 14 0.2857142857142857 7 420.0 XmlEngine_tutorial - Apr 7, 2006 35/51
Peter 2002 5 2 2.5 8 480.0 Peter 2002 5 15 0.3333333333333333 3 180.0 Total 38.0 Configuration file: Example13.xml <?xml version="1.0"?> <REPORT> <template file="example13.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <PARAMETER id="param60" name="param60" default="60"/> <FUNCTION id="funcdivi" name="divide" arg1="fieldmonth" arg2="fieldday"/> <FUNCTION id="funcminutes" name="multiply" arg1="fieldhours" arg2="param60"/> <SECTION id="sectiondetail"/> </structure> </REPORT> In other examples we have seen the SUM, COUNT and MED functions. The only difference between those and DIVIDE, MOD, MULTIPLY, ADD is in the arguments they receive. On this example we use MULTIPLY and DIVIDE functions and we also add two new columns in the HTML template: <td>month/day</td> <td>minutes</td> XmlEngine_tutorial - Apr 7, 2006 36/51
And for each row of data: <td id="funcdivi">x480</td> <td id="funcminutes">x480</td> In the XML document: <PARAMETER id="param60" name="param60" default="60"/> <FUNCTION id="funcdivi" name="divide" arg1="fieldmonth" arg2="fieldday"/> <FUNCTION id="funcminutes" name="multiply" arg1="fieldhours" arg2="param60"/> To invoke the servlet you can use the following URL: http://localhost:8080/xmlengine/xmlengine.html?re port=examples\example13 VII.14 Example 14: the EQUAL function This example shows how to use the equal function. Output of example 14 Hours of labour - 6 parts N. Employee Year Month Day Hours Accumulate 1.0 Johann 2002 4 1 7 7.0 2.0 Johann 2002 5 15 8 15.0 3.0 Peter 2001 12 26 5 20.0 4.0 Peter 2002 4 14 7 27.0 5.0 Peter 2002 5 2 8 35.0 6.0 Peter 2002 5 15 3 38.0 Total 38.0 Configuration file: Example14.xml <?xml version="1.0"?> <REPORT> <template file="example14.html" /> <structure name="structure1"> <SQL> XmlEngine_tutorial - Apr 7, 2006 37/51
SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <FUNCTION id="funccounter" name="equal" arg1="funccountparts"></function> <FUNCTION id="funcacumulate" name="equal" arg1="funcsumhours"></function> <SECTION id="sectiondetail"/> </structure> </REPORT> The EQUAL function obtains counters and calculates accumulated sums in lists. For example, if we want to enumerate the lines of a list and have a column with the accumulated value we need to include two equal functions. <FUNCTION id="funccounter" name="equal" arg1="funccountparts"></function> <FUNCTION id="funcacumulate" name="equal" arg1="funcsumhours"></function> The first function calculates the actual value in the funccountparts function that indicates the line number. The second function represents the current value in the line of funcsumhours function. VII.15 Example 15: Functions and fields format This example shows how to use fields and functions. Output of example 15 Hours of labour - 6 parts XmlEngine_tutorial - Apr 7, 2006 38/51
N. Employee Year Month Day Hours Accumulate 1 Johann 2002 4 1 7 7.0 2 Johann 2002 5 15 8 15.0 3 Peter 2001 12 26 5 20.0 4 Peter 2002 4 14 7 27.0 5 Peter 2002 5 2 8 35.0 6 Peter 2002 5 15 3 38.0 Total 38.0 Configuration file: Example15.xml <?xml version="1.0"?> <REPORT> <template file="example15.html" /> <structure name="structure1"> <SQL> SELECT Employee, ReportYear, ReportMonth, ReportDay, Hours FROM Hours </SQL> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <FUNCTION id="funccounter" name="equal" arg1="funccountparts" format="integerinform"></function> <FUNCTION id="funcacumulate" name="equal" arg1="funcsumhours"></function> <SECTION id="sectiondetail"/> </structure> </REPORT> In the previous example the line number appears in decimal format. XmlEngine defines different formats to apply to output values. This can be XmlEngine_tutorial - Apr 7, 2006 39/51
achieved with the format attribute of <field> and <function> tags. XmlEngine_tutorial - Apr 7, 2006 40/51
VIII.Application examples VIII. Application examples VIII.1 Demo application without database This demo application shows an XmlEngine application that does not use a database connection. This example shows every category from a log4j configuration file, updating the selected items. In the following output you can see the categories and their priorities. You can use the user interface elements to change the selection. Screen capture of the Log4J demo application Log4j Demo We have an HTML file (SetPriority.html): <FORM METHOD=GET ACTION="#"> <SELECT NAME="priority" SIZE="5"> <OPTION value="debug" selected>debug</option> <OPTION value="info">info</option> <OPTION value="warn">warn</option> <OPTION value="error">error</option> <OPTION value="fatal">fatal</option> </SELECT> <INPUT TYPE="submit" value="priority Update"> <p> <TABLE> <TR> <TH>Category</TH> <TH>Priority</TH> </TR> <DIV id="sectiondetail"> <TR> <TD> <INPUT id="fieldcatval" TYPE="radio" NAME="category" value="x"> <SPAN id="fieldcategory">xcategory</span></td> <TD id="fieldpriority">xpriority</td> </TR> </DIV> </TABLE> </FORM> XmlEngine_tutorial - Apr 7, 2006 41/51
VIII.Application examples We have an XML file (SetPriority.xml): <?xml version="1.0"?> <REPORT> <template file="setpriority.html" /> <structure name="structure1"> <FIELD id="fieldcategory">category</field> <FIELD id="fieldcatval" attribute="value">category</field> <FIELD id="fieldpriority">priority</field> <SECTION id="sectiondetail"/> </structure> </REPORT> The XML file (SetPriority.xml) is similar to the report generation XML files. The only difference is that it not a SQL query. We have a ServletSetPriority.java file. It shows de Log4j categories and it updates. import java.io.printwriter; import java.io.ioexception; import java.io.file; import javax.servlet.*; import javax.servlet.http.*; import org.openbravo.xmlengine.xmlengine; import org.openbravo.xmlengine.xmldocument; import org.apache.log4j.category; import org.apache.log4j.priority; import org.apache.log4j.propertyconfigurator; public class ServletSetPriority extends HttpServlet { public XmlEngine xmlengine=null; static Category log4jservletsetpriority = Category.getInstance(ServletSetPriority.class); public void init (ServletConfig config) { String prefix = config.getservletcontext().getrealpath("/"); PropertyConfigurator.configure(prefix+"WEB- INF/config/log4j.lcf"); xmlengine = new XmlEngine(); xmlengine.filexmlengineformat = new File (prefix+"web-inf/config/format.xml"); XmlEngine_tutorial - Apr 7, 2006 42/51
VIII.Application examples xmlengine.filebaselocation = new File(prefix+"WEB-INF/classes"); xmlengine.initialize(); public void doget(httpservletrequest request, HttpServletResponse response) throws IOException, ServletException { dopost(request,response); public void dopost(httpservletrequest request, HttpServletResponse response) throws IOException, ServletException { String strcategory = request.getparameter("category"); String strpriority = request.getparameter("priority"); if (strcategory!= null && strpriority!= null) { Category category = Category.getInstance(strCategory); Priority priority = Priority.toPriority(strPriority); category.setpriority(priority); printpage(response); void printpage(httpservletresponse response) throws IOException, ServletException { log4jservletsetpriority.debug("output: Page"); response.setcontenttype("text/html"); PrintWriter out = response.getwriter(); XmlDocument xmldocument = xmlengine.readxmltemplate("setpriority").createxm ldocument(); xmldocument.setdata("structure1",categorydata.getcategories()); out.println(xmldocument.print()+" v22"); out.close(); public String getservletinfo() { XmlEngine_tutorial - Apr 7, 2006 43/51
VIII.Application examples return "Servlet that asign a priority to a Category"; We need to import several packages from the XmlEngine package: import org.openbravo.xmlengine.xmlengine; import org.openbravo.xmlengine.xmldocument; XmlDocument is a class that represents an XmlTemplate and XmlEngine is the class that represents the XmlEngine engine. The ServletSetPriority servlet extends HttpServlet. The init() function initializes an XmlEngine object. This object is later used in the printpage() function, where output string is generated: response.setcontenttype("text/html"); PrintWriter out = response.getwriter(); After this, the SetPriority.xml file is read using the readxmltemplate function in the XmlEngine object. It returns an xmltemplate object which contains the template structure. Using this template the createxmldocument functions creates an XmlDocument object. XmlDocument xmldocument = xmlengine.readxmltemplate("setpriority").createxm ldocument(); Then we introduce the data in XmlDocument using setdata.java, reciving as an argument the structure name and the data object. xmldocument.setdata("structure1",categorydata.get Categories()); And, finally, it prints the output and passes to the PrintWriter: out.println(xmldocument.print()); out.close(); The setdata method from XmlDocument is the one who passes the data to XmlEngine, so this can later fill the template. The purpose of using a interface is to accept data from different sources. This interface is defined at FieldProvider: package org.openbravo.data; public interface FieldProvider { public String getfield(string fieldname); Every class that passes data to XmlEngine must have the getfield method, which has as argument the name of the field. The class used on this demo is CategoryData: import java.util.*; XmlEngine_tutorial - Apr 7, 2006 44/51
VIII.Application examples import org.openbravo.data.fieldprovider; import org.apache.log4j.category; public class CategoryData implements FieldProvider { static Category log4jcategorydata = Category.getInstance(CategoryData.class); public String category; public String priority; public String getfield(string fieldname) { if (fieldname.equals("category")) return category; else if (fieldname.equals("priority")) return priority; else { log4jcategorydata.debug("no existe el campo: " + fieldname); return null; public static CategoryData[] getcategories() { Vector vector = new Vector(0); for (Enumeration e = Category.getCurrentCategories(); e.hasmoreelements() ;) { Category categoryitem = (Category)e.nextElement(); CategoryData categorydata = new CategoryData(); categorydata.category = categoryitem.getname(); if (categoryitem.getpriority()!= null) { categorydata.priority = categoryitem.getpriority().tostring(); vector.addelement(categorydata); CategoryData categorydata[] = new CategoryData[vector.size()]; vector.copyinto(categorydata); XmlEngine_tutorial - Apr 7, 2006 45/51
VIII.Application examples return(categorydata); VIII.2 Demo application with a database connection Many applications obtain their data from a database. This demo shows how an application can access XmlEngine with data obtained data from a database. This sample uses a template and configuration files similar to the ones used on the fourth example. The configuration files looks like: Configuration file: hours4.xml <?xml version="1.0"?> <REPORT> <template file="list4.html" /> <structure name="structure1"> <FIELD id="fieldemployee">employee</field> <FIELD id="fieldyear">reportyear</field> <FIELD id="fieldmonth">reportmonth</field> <FIELD id="fieldday">reportday</field> <FIELD id="fieldhours">hours</field> <FUNCTION id="funccountparts" name="count">hours</function> <FUNCTION id="funcsumhours" name="sum">hours</function> <SECTION id="sectiondetail"/> </structure> </REPORT> The <template> tag indicates which template is used. The following servlet generates the same output that sample four but as an application. Configuration file: HoursList.java import org.openbravo.xmlengine.xmlengine; import org.openbravo.xmlengine.xmldocument; import java.io.*; import java.sql.*; import javax.servlet.*; XmlEngine_tutorial - Apr 7, 2006 46/51