ERP 2.50:Developers Guide/Concepts/XMLEngine
Contents |
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.
This document explains, by examples, the basic concepts of XmlEngine and how is integrated in Openbravo ERP.
Module
All the code used in this document, is available as a module: Concepts - XmlEngine. Open your module management console, search and install the Concepts - XmlEngine module.
Module Changelog
1.0.3
- Changed mapping name based on new naming rules
1.0.2
- Fixed installation issue in Oracle
1.0.1
- Added template format attribute, Sample 6
1.0.0
- Initial module with Samples 1 to 5
Testing the code
To be able to test the code, open your web browser and go to http://host:port/context/org.openbravo.concepts.xmlengine/xmlengine-sample.html e.g. http://localhost:8080/openbravo/org.openbravo.concepts.xmlengine/xmlengine-sample.html
Simple example (Sample 1)
The HTML template
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>XmlEngine Sample</title> </head> <body> <h1>XmlEngine sample: simple</h1> <p> This HTML template (sample1.html) was loaded through the template sample1.xml </p> </body> </html>
The XML template
<?xml version="1.0" encoding="UTF-8"?> <REPORT> <TEMPLATE file="sample1.html"/> </REPORT>
The Java code
private void printSample1(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { PrintWriter out = response.getWriter(); response.setContentType("text/html; charset=UTF-8"); // Load xml template XmlDocument xmlDocument = xmlEngine.readXmlTemplate("org/openbravo/concepts/xmlengine/sample1") .createXmlDocument(); // Print the loaded template out.println(xmlDocument.print()); out.close(); }
You load the XML template with the readXmlTemplate helper function, and create a new xmlDocument. The sample1.xml file has a TEMPLATE with a file attribute, this attribute points to the HTML file.
Diagram
Passing parameters (Sample 2)
The HTML template
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>XmlEngine Sample</title> </head> <body> <h1>XmlEngine sample: Passing parameters</h1> <p id="paramParagraph">This text will be replaced</p> <p>The whole <strong>p</strong> tag content was replaced with the parameter value.</p> </body> </html>
The XML template
<?xml version="1.0" encoding="UTF-8"?> <REPORT> <TEMPLATE file="sample2.html"/> <!-- id attribute must be same than in the html template --> <!-- name attribute is used by the controller (java) to set the value --> <PARAMETER id="paramParagraph" name="paragraph" default="" /> </REPORT>
The Java code
private void printSample2(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { PrintWriter out = response.getWriter(); response.setContentType("text/html; charset=UTF-8"); XmlDocument xmlDocument = xmlEngine.readXmlTemplate("org/openbravo/concepts/xmlengine/sample2") .createXmlDocument(); // Set the parameter paragraph xmlDocument.setParameter("paragraph", "Lorem Ipsum is simply dummy text of " + "the printing and typesetting industry. " + "Lorem Ipsum has been the industry's standard dummy text ever since the 1500s"); out.println(xmlDocument.print()); out.close(); }
Diagram
Replacing part of a attribute (Sample 3)
The HTML template
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>XmlEngine Sample</title> </head> <body> <h1>XmlEngine sample: Passing parameters</h1> <p>This <span id="paramStyle" style="text-decoration: xxx">underlined text</span> style was passed as parameter</p> <p>The <strong>xxx</strong> part of the style attribute was replaced with the parameter value.</p> </body> </html>
We want to replace the xxx string with a valid CSS text-decoration string.
The XML template
<?xml version="1.0" encoding="UTF-8"?> <REPORT> <TEMPLATE file="sample3.html"/> <!-- id attribute must be same than in the html template --> <!-- name attribute is used by the controller (java) to set the value --> <!-- attribute is the one defined in the html template --> <!-- replace is the string that will be replaced by the parameter on the defined attribute content --> <PARAMETER id="paramStyle" name="style" attribute="style" replace="xxx" /> </REPORT>
The Java code
private void printSample3(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { PrintWriter out = response.getWriter(); response.setContentType("text/html; charset=UTF-8"); XmlDocument xmlDocument = xmlEngine.readXmlTemplate("org/openbravo/concepts/xmlengine/sample3") .createXmlDocument(); // Set the parameter style that will replace xxx string xmlDocument.setParameter("style", "underline"); out.println(xmlDocument.print()); out.close(); }
Diagram
Filling a table with setData (Sample 4)
The HTML template
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <style type="text/css"> * { margin: 0; padding: 0; } #product-list { width: 60%; margin: auto; } #product-list th { color: #003399; text-align: left; } </style> <title>XmlEngine Sample</title> </head> <body> <h1>XmlEngine sample: Filling a table with setData</h1> <p>The table is populated with an array of data</p> <table id="product-list"> <thead> <tr> <th scope="col" id="th-productid">Product Id</th> <th scope="col" id="th-value">Value</th> <th scope="col" id="th-name">Name</th> </tr> </thead> <tbody id="sectionDetail"> <tr> <td id="fieldProductId"></td> <td id="fieldValue"></td> <td id="fieldName"></td> </tr> </tbody> </table> </body> </html>
The XML template
<?xml version="1.0" encoding="UTF-8"?> <REPORT> <TEMPLATE file="sample4.html"/> <STRUCTURE name="structure1"> <FIELD id="fieldProductId">m_product_id</FIELD> <FIELD id="fieldValue">value</FIELD> <FIELD id="fieldName">name</FIELD> <SECTION id="sectionDetail" /> </STRUCTURE> </REPORT>
The Java code
private void printSample4(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { PrintWriter out = response.getWriter(); response.setContentType("text/html; charset=UTF-8"); XmlDocument xmlDocument = xmlEngine.readXmlTemplate("org/openbravo/concepts/xmlengine/sample4") .createXmlDocument(); XmlEngineSampleData[] data = XmlEngineSampleData.select(this); xmlDocument.setData("structure1", data); out.println(xmlDocument.print()); out.close(); }
Diagram
Using a XMLEngine function (Sample 5)
The HTML template
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <style type="text/css"> * { margin: 0; padding: 0; } #product-list { width: 60%; margin: auto; } #product-list th { color: #003399; text-align: left; } .row_0 { background: #fff; } .row_1 { background: #dddaec; } </style> <title>XmlEngine Sample</title> </head> <body> <h1>XmlEngine sample: Filling a table with setData and using a function</h1> <p>The row CSS class is calculated with a XmlEngine function</p> <table id="product-list"> <thead> <tr> <th scope="col" id="th-productid">Product Id</th> <th scope="col" id="th-value">Value</th> <th scope="col" id="th-name">Name</th> </tr> </thead> <tbody id="sectionDetail"> <tr class="row_yy" id="fieldEvenOddRow"> <td id="fieldProductId"></td> <td id="fieldValue"></td> <td id="fieldName"></td> </tr> </tbody> </table> </body> </html>
The XML template
<?xml version="1.0" encoding="UTF-8"?> <REPORT> <TEMPLATE file="sample5.html"/> <!-- param2 will be used in the MODULE function --> <!-- the default attribute in parameters is the default value when no data is passed --> <PARAMETER id="param2" name="param2" default="2"/> <STRUCTURE name="structure1"> <!-- rownum field is the record number defined in the xsql --> <FIELD id="fieldRownum">rownum</FIELD> <!-- Function definition --> <!-- id = tag id of the html template --> <!-- name = name of the function to be called, MODULE, ADD, SUM, etc --> <!-- arg1 = first argument of the function --> <!-- arg2 = second argument of the function --> <!-- format = number formatting defined in Format.xml file --> <!-- attribute = html attribute we want to change --> <!-- replace = string pattern we want to replace/change --> <FUNCTION id="fieldEvenOddRow" name="MODULE" arg1="fieldRownum" arg2="param2" format="integerEdition" attribute="class" replace="yy"/> <FIELD id="fieldProductId">m_product_id</FIELD> <FIELD id="fieldValue">value</FIELD> <FIELD id="fieldName">name</FIELD> <SECTION id="sectionDetail" /> </STRUCTURE> </REPORT>
The Java code
private void printSample5(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { PrintWriter out = response.getWriter(); response.setContentType("text/html; charset=UTF-8"); XmlDocument xmlDocument = xmlEngine.readXmlTemplate("org/openbravo/concepts/xmlengine/sample5") .createXmlDocument(); XmlEngineSampleData[] data = XmlEngineSampleData.select(this); xmlDocument.setData("structure1", data); out.println(xmlDocument.print()); out.close(); }
Diagram
Formatting numbers (Sample 6)
The HTML template
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <style type="text/css"> * { margin: 0; padding: 0; } #number-list { width: 40%; margin-left: 10px; } #number-list th { color: #003399; text-align: left; } td { text-align: right; } p { margin: 10px; } </style> <title>XmlEngine Sample</title> </head> <body> <h1>XmlEngine sample: Formatting numbers</h1> <p>The number received from the database is 123456.8642</p> <p>The <em>format</em> attribute can be used in PARAMETER, FIELD tags</p> <p>Here you have how is rendered using the different number formats</p> <table id="number-list"> <thead> <tr> <th scope="col" colspan="2">Format name</th> </tr> </thead> <tbody id="sectionDetail"> <tr> <th scope="row" id="th-1">euroInform</th> <td id="fieldeuroInform"></td> </tr> <tr> <th scope="row" id="th-2">euroRelation</th> <td id="fieldeuroRelation"></td> </tr> <tr> <th scope="row" id="th-3">euroEdition</th> <td id="fieldeuroEdition"></td> </tr> <tr> <th scope="row" id="th-4">euroExcel</th> <td id="fieldeuroExcel"></td> </tr> <tr> <th scope="row" id="th-5">priceInform</th> <td id="fieldpriceInform"></td> </tr> <tr> <th scope="row" id="th-6">priceRelation</th> <td id="fieldpriceRelation"></td> </tr> <tr> <th scope="row" id="th-7">priceEdition</th> <td id="fieldpriceEdition"></td> </tr> <tr> <th scope="row" id="th-8">integerInform</th> <td id="fieldintegerInform"></td> </tr> <tr> <th scope="row" id="th-9">integerRelation</th> <td id="fieldintegerRelation"></td> </tr> <tr> <th scope="row" id="th-10">integerEdition</th> <td id="fieldintegerEdition"></td> </tr> <tr> <th scope="row" id="th-11">integerExcel</th> <td id="fieldintegerExcel"></td> </tr> <tr> <th scope="row" id="th-12">priceExcel</th> <td id="fieldpriceExcel"></td> </tr> <tr> <th scope="row" id="th-13">qtyRelation</th> <td id="fieldqtyRelation"></td> </tr> <tr> <th scope="row" id="th-14">qtyEdition</th> <td id="fieldqtyEdition"></td> </tr> <tr> <th scope="row" id="th-15">qtyExcel</th> <td id="fieldqtyExcel"></td> </tr> <tr> <th scope="row" id="th-16">generalQtyRelation</th> <td id="fieldgeneralQtyRelation"></td> </tr> <tr> <th scope="row" id="th-17">generalQtyEdition</th> <td id="fieldgeneralQtyEdition"></td> </tr> <tr> <th scope="row" id="th-18">generalQtyExcel</th> <td id="fieldgeneralQtyExcel"></td> </tr> <tr> <th scope="row" id="th-19">amountInform</th> <td id="fieldamountInform"></td> </tr> </tbody> </table> </body> </html>
The XML template
<?xml version="1.0" encoding="UTF-8"?> <REPORT> <TEMPLATE file="sample6.html"/> <STRUCTURE name="structure1"> <!-- You can format a numeric value using the format attribute, you just need to pick a format name from the Format.xml config file --> <FIELD id="fieldeuroInform" format="euroInform">number</FIELD> <FIELD id="fieldeuroRelation" format="euroRelation">number</FIELD> <FIELD id="fieldeuroEdition" format="euroEdition">number</FIELD> <FIELD id="fieldeuroExcel" format="euroExcel">number</FIELD> <FIELD id="fieldpriceInform" format="priceInform">number</FIELD> <FIELD id="fieldpriceRelation" format="priceRelation">number</FIELD> <FIELD id="fieldpriceEdition" format="priceEdition">number</FIELD> <FIELD id="fieldintegerInform" format="integerInform">number</FIELD> <FIELD id="fieldintegerRelation" format="integerRelation">number</FIELD> <FIELD id="fieldintegerEdition" format="integerEdition">number</FIELD> <FIELD id="fieldintegerExcel" format="integerExcel">number</FIELD> <FIELD id="fieldpriceExcel" format="priceExcel">number</FIELD> <FIELD id="fieldqtyRelation" format="qtyRelation">number</FIELD> <FIELD id="fieldqtyEdition" format="qtyEdition">number</FIELD> <FIELD id="fieldqtyExcel" format="qtyExcel">number</FIELD> <FIELD id="fieldgeneralQtyRelation" format="generalQtyRelation">number</FIELD> <FIELD id="fieldgeneralQtyEdition" format="generalQtyEdition">number</FIELD> <FIELD id="fieldgeneralQtyExcel" format="generalQtyExcel">number</FIELD> <FIELD id="fieldamountInform" format="amountInform">number</FIELD> <SECTION id="sectionDetail" /> </STRUCTURE> </REPORT>
The Java code
private void printSample6(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { PrintWriter out = response.getWriter(); response.setContentType("text/html; charset=UTF-8"); XmlDocument xmlDocument = xmlEngine.readXmlTemplate("org/openbravo/concepts/xmlengine/sample6") .createXmlDocument(); XmlEngineSampleData[] data = XmlEngineSampleData.selectNumber(this); xmlDocument.setData("structure1", data); out.println(xmlDocument.print()); out.close(); }
Similar to the previous example, the selectNumber method gets a numeric value and pass it with the setData method.
Languages: |
ERP 2.50:Developers Guide/Concepts/Servlet Structure | ERP 2.50:Developers Guide/Concepts/SQLC