# Tutorial

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.kut` and `sample1.kud` that are distributed with &kugar;.

## Creating the report template with &kudesigner;

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 set millimeters. New Report dialog

New report is now created and all buttons on the Items Toolbar and Sections Toolbar became now enabled (the corresponding menu items from Items and Sections are enabled too). Empty Report dialog

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 at the first and last pages 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 has identical structure (i.e. fields). If data structure is more complex or it is organized according to a master-detail relationship, more detail levels should be created. See `sample3.kut` and `sample3.kud` for an example of how that can be done. Refer to the template elements descriptions for the additional information.

Sections are added by using Sections menu or a Sections Toolbar. Now add report header and footer, page header and footer and then detail. When adding detail section, set it's level to 0 as shown on the screenshot below. Setting detail level

Our report should look now like this one on the screenshot. Report with sections

All our sections have a predefined height - 50mm. Let's change it. To do this &RMB; on the Report Header section or click Edit Properties button on the Edit Toolbar and then choose a section. Properties window should be shown. Height of the section editing

Now set a Report Header's height to 70. Let's perform that procedure for all other sections. Set Page Header's height to 45 and Detail's to 30. Page and Report Footers should be 32 mm 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. Text and background colors among with fonts can be changes for Label. Border line types and line colors are also customizable. Field can be placed onto a detail sections. 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. General report look 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. Choosen 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 section's height).

So, let's add labels to the report header and page header like shown on the screenshot below. Note, that the Mutiny Bay Software label has it's 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) divided by comma.

Add also 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`]

Out page footer is a good place to show current date and page number, so add two special fields and set their Type properties to 0 and 1. 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 Calculated Field for copies field. To acquire a sum(copies) set calculated field's Field property to copies and CalculationType to 1 (sum function).

Finally, our report template should look like this. Complete report

## Creating the report data file

Generally speaking, data files may be created in several vays. One can use xsl transformation tables to generate proper xml from another xml document (like KSpread spreadsheet), another will use 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.kud` 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.kut">
        <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>

## Generating report

At this moment we have a report template (`sample1.kut`) and a report data (`sample1.kud`).

To generate a report, type following command in the shell: `kugar `-r sample1.kut` `-d sample1.kud``

This will bring you a Kugar shell window with the report generated. Generated report