Alexander Dymo

cloudtemple@mksat.net

Phil Thompson

phil@river-bank.demon.co.uk

This tutorial attempts to be a brief introduction to Kugar. You will create a sample report template with &kudesigner;, a sample data file and finally generate a complete report. The source code for sample templates and data files can be found in sample1.ktf and sample1.kdf that are distributed with &kugar;. Run Kugar Designer by typing kudesigner in the shell. After you start the designer, choose File|New and set the page size to Letter and paper orientation to Landscape. Set the left and right margins to 48, top and bottom margins to 40. All dimensions in &kudesigner; (page margins, sizes, positions, &etc;) are measured in millimeters. New Report dialog A new report is now created and all buttons on the Items Toolbar and Sections Toolbar are now enabled (the corresponding menu items from Items and Sections are also enabled). Empty Report window Now it is the time to add some sections to the report and determine their sizes. We will add report header and footer, page header and footer and a single detail section. Report headers and footers are printed on the first page and on the last page of the report before and after any other report data accordingly. Report footers are good places for calculated fields. Page headers and footers are printed at the top and bottom of each page. Our report will have one detail section with level 0. This means that all our data rows have identical structure (&ie; fields). If the data structure is more complex or it is organized according to a master-detail relationship, more detail levels should be created. See sample3.ktf and sample3.kdf for an example of how that can be done. Refer to the template elements descriptions for additional information. Sections are added by using Sections menu or a Sections Toolbar. Now add a report header and footer, a page header and footer and then a detail section. When adding a detail section, set its level to 0 as shown on the screenshot below. Setting the detail level Our report should now look like this one in the screenshot. Report with sections All our sections have a predefined height - 50mm. Let's change it. To do this &RMB; click on the Report Header section or click the Edit Properties button on the Edit Toolbar and then choose a section. The Properties window should be shown. Height of the section editing Now set the Report Header's height to 70. Let's perform that procedure for all other sections. Set the Page Header's height to 45 and the Detail's to 30. The Page and Report Footers should be 32 mm in height. A report template with properly sized sections is ready to be filled with report items. Report with sized sections You can now add items to the sections on the report. Five different types of items can be added to the report. Label is a rectangular area that can have borders and can be filled by any kind of textual data. The Label's foreground and background colors, as well as fonts, can be changed. Border line types and line colors are also customizable. Fields can be placed on to a detail section. Fields represent data fields; their values will be collected from a data file while generating a report. Counts, sums, averages, &etc; for field values can be printed on the report by means of Calculated Fields. Specials are labels with predefined text, such as current date or page number. The general report appearance can be refined with Lines. To add a report item click the corresponding item button on the Items Toolbar and place (click) it on the section. The chosen item will be placed on the selected section with the upper left corner at the given coordinates. Other properties are set to default values and can be changed with the Report Item Options dialog (the same way we used to change the section's height). So, let's add labels to the report header and page header as shown on the screenshot below. Note that the Mutiny Bay Software label has its BorderStyle and BorderWidth set to 0 and Software Inventory Report - 1mm. Any colors are set as a combination of three values (RGB - red,green,blue) separated by commas. We will also add field elements to the detail section. Just assume we have four fields - title, version, platform and copies. So, four Field elements should be placed and their Field properties set. Note that Text property is automatically set to [field_name]. Our page footer is a good place to show the current date and page number, so add two special fields and set their Type properties to 0 and 1. A special with Type=0 will represent date and one with Type=1 - page number. Note that special's Text property is changed automatically. The last element to be placed is a Calculated Field for the copies field. To acquire a sum (copies) set the calculated field's Field property to copies and CalculationType to 1 (sum function). Finally, our report template should look like this: Complete report Generally speaking, data files may be created in several ways. Some will use xsl transformation tables to generate proper &XML; from another &XML; document (like a &kspread; spreadsheet); others will use their own program to fetch data from a database and fill the data file. In this tutorial we will simply create it by hand. The source code for the example can be found in file sample1.kdf or copied from the example below. <?xml version=1.0 encoding=UTF-8?> <!DOCTYPE KugarData [ <!ELEMENT KugarData (Row* )> <!ATTLIST KugarData Template CDATA #REQUIRED> <!ELEMENT Row EMPTY> <!ATTLIST Row level CDATA #REQUIRED title CDATA #REQUIRED version CDATA #REQUIRED platform CDATA #REQUIRED copies CDATA #REQUIRED> ]> <KugarData Template="sample1.ktf"> <Row level="0" title=" BRU" version="15.0" platform="x86" copies="1"/> <Row level="0" title=" Caldera Open Linux" version="2.2" platform="x86" copies="3"/> <Row level="0" title=" K Desktop" version="1.1.1" platform="x86" copies="1"/> <Row level="0" title=" Netscape Communicator" version="4.6" platform="x86" copies="10"/> <Row level="0" title=" Redhat Linux" version="5.0" platform="x86" copies="11"/> <Row level="0" title=" Redhat Linux" version="5.1" platform="x86" copies="12"/> <Row level="0" title=" Redhat Linux" version="5.2" platform="x86" copies="14"/> <Row level="0" title=" Redhat Linux" version="6.0" platform="x86" copies="15"/> <Row level="0" title=" Star Office" version="5.0" platform="x86" copies="1"/> <Row level="0" title=" Star Office" version="5.1" platform="x86" copies="3"/> <Row level="0" title=" Microsoft Windows NT" version="3.1" platform="x86" copies="1"/> <Row level="0" title=" Microsoft Windows NT" version="3.51" platform="x86" copies="1"/> <Row level="0" title=" Microsoft Windows NT" version="4.0" platform="x86" copies="1"/> <Row level="0" title=" Microsoft Windows NT" version="5.0" platform="x86" copies="1"/> <Row level="0" title=" Sun Solaris" version="2.5" platform="Sparc" copies="1"/> </KugarData> At this moment we have a report template (sample1.ktf) and a report data file (sample1.kdf). To generate a report, type the following command in the shell: kugar -r sample1.ktf -d sample1.kdf This will bring up a &kugar; shell window with the report generated. Generated report