<!-- If you want to validate or edit this document separately, uncomment
this prolog

<?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd">

-->
<chapter id="tutorial">
<title
>Didacticiel</title>

<para
>Ce didacticiel tente d'être une brève introduction à Kugar.</para>

<para
>Vous créerez un modèle de rapport exemple avec &kudesigner;, un fichier de données exemple et finalement, produirez un rapport complet.</para>

<para
>Le code source pour les modèles exemples et les fichiers de données peut se trouver dans <filename
>sample1.kut</filename
> et <filename
>sample1.kud</filename
> qui sont distribués avec &kugar;.</para>


<sect1 id="tut-1">
<title
>Création d'un modèle de rapport avec &kudesigner;</title>

<para
>Lancez Kugar Designer en saisissant <command
>kudesigner</command
> en ligne de commande. </para>

<para
>Après avoir démarré de concepteur, choisissez <guimenu
>Fichier</guimenu
>|<guilabel
>Nouveau</guilabel
> et déterminez la taille de la page à <guilabel
>Letter</guilabel
> et l'orientation du papier sur <guilabel
>Paysage</guilabel
>. Déterminez les marges gauche et droite à 48 et les marges haute et basse à 40. Toutes les dimensions dans &kudesigner; (marges, positions, tailles, &etc;) sont données en millimètres. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_file_new.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Dialogue <interface
>Nouveau rapport</interface
></phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Le nouveau rapport est maintenant créé et tous les boutons sur la <guilabel
>Barre d'éléments</guilabel
> et la <guilabel
>Barre de sections</guilabel
> deviennent activés (les éléments de menu correspondants de <guilabel
>Items</guilabel
> et <guilabel
>Sections</guilabel
> sont aussi activés). <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_empty_report.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Dialogue de rapport vide</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Maintenant, c'est le moment d'ajouter des sections au rapport et de déterminer leurs tailles. Nous ajouterons des <link linkend="report-header-and-footer"
>en-têtes et pieds de rapport</link
>, <link linkend="page-header-and-footer"
>en-têtes et pieds de page</link
> et une simple section <link linkend="detail"
>détail</link
>. Les en-têtes et pieds de rapports sont affichés sur les première et dernière pages du rapport et après toute autre donnée du rapport. Les pieds de rapport sont de bons endroits pour les <link linkend="calculated-field-element"
>champs calculés</link
>. Les en-têtes et pieds de pages sont affichés en haut et en bas de chaque page. Notre rapport aura une section de détail avec le niveau 0. Ceci signifie que toutes nos lignes de données ont une structure identique (c'est-à-dire les champs). Si la structure des données est plus complexe ou si elle est organisée selon une relation maître-détail, il faut créer plus de niveaux de détail. Voyez <filename
>sample3.kut</filename
> et <filename
>sample3.kud</filename
> pour un exemple de la manière dont cela peut être fait. Reportez-vous à la <link linkend="template-elements"
>description des éléments de modèle</link
> pour d'autres informations. </para>

<para
>Les sections sont ajoutées en utilisant le menu <guilabel
>Sections</guilabel
> ou une <guilabel
>Barre d'outils de sections</guilabel
>. Maintenant, ajoutons un en-tête et un pied de page, puis le détail. Lors de l'ajout de la section de détails, mettons son niveau à 0 comme montré sur l'écran ci-dessous. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_set_level.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Déterminer le niveau de détail</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Notre rapport devrait maintenant ressembler à celui de la capture d'écran. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_look1.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Rapport avec des sections</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Toutes nos sections ont une hauteur prédéfinie - 50 mm. Changeons-la. Pour ce faire, cliquons du &BDS; sur la section En-tête du rapport ou cliquons sur le bouton <guilabel
>Modifier les propriétés</guilabel
> sur la <guilabel
>Barre d'outils d'édition</guilabel
>. La fenêtre de propriétés doit être affichée. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_edit_height.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Hauteur de la section éditable</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Maintenant, donnons à l'en-tête du rapport la hauteur de 70. Effectuons cette procédure pour toutes les autres sections. Fixons la hauteur de l'en-têtede page à 45 et les détails à 30. Les pieds de page et de rapport doivent être à 32 mm. </para>

<para
>Un modèle de rapport avec des tailles de section proprement établies est prêt à être rempli d'éléments de rapport. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_look2.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Rapport avec des sections à taille définie</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para
>Vous pouvez maintenant ajouter des éléments aux sections sur le rapport. Cinq différents types d'éléments peuvent être ajoutés sur le rapport. <link linkend="label-element"
>Libellé</link
> est une zone rectangulaire qui a des bordures et peut être remplie de n'importe quelle sorte de données textuelles. Le texte et les couleurs de fond et les polices peuvent être changés pour la bordure du libellé et les couleurs des lignes sont aussi personnalisables. <link linkend="field-element"
>Champ</link
> peut être placé sur une section de détails. Les champs représentent les champs de données, leurs valeurs seront collectées d'un fichier de données lors de la génération du rapport. Les comptes, les sommes, moyennes, etc. pour les valeurs des champs peuvent être imprimés sur le rapport au moyen de <link linkend="calculated-field-element"
>Champs calculés</link
>. <link linkend="special-element"
>Specials</link
> sont des libellés avec du texte prédéfini, comme la date courante ou le numéro de page. L'aspect général du rapport peut être raffiné avec <link linkend="line-element"
>Ligne</link
>. </para>

<para
>Pour ajouter un élément au rapport, cliquez sur le bouton de l'élément correspondant sur la <guilabel
>barre d'outils d'éléments</guilabel
> et placez-le (clic) sur la section. L'élément choisi sera placé sur la section sélectionnée avec le coin supérieur gauche aux coordonnées données. Les autres propriétés sont mises aux valeurs par défaut et peuvent être changées avec le dialogue <guilabel
>Options d'éléments de rapports</guilabel
> (de la même manière que nous avons utilisée pour changer la hauteur des sections). </para>

<para
>Ainsi, ajoutons des libellés à l'en-tête de rapport et à l'en-tête de page comme montré sur la capture d'écran ci-dessous. Notez que le libellé <quote
>Mutin Bay Software</quote
> a son <guilabel
>BorderStyle</guilabel
> et <guilabel
>BorderWidth</guilabel
> positionnés à 0 et <quote
>Software Inventory Report</quote
> - 1 mm. Toutes les couleurs sont déterminées comme une combinaison de trois valeurs (RGB - rouge, vert, bleu), séparées par des virgules. </para>

<para
>Ajoutez aussi des éléments de champ à la section détails. Supposons simplement que nous avons quatre champs - titre, version, plate-forme et copies. Ainsi, quatre éléments <guilabel
>Champ</guilabel
> doivent être placés et leur propriétés de <guilabel
>Champ</guilabel
> déterminées. Notez que la propriété de <guilabel
>Text</guilabel
> est positionnée automatiquement sur <quote
>[<userinput
>field_name</userinput
>]</quote
> </para>

<para
>Le pied de page est une bonne place pour montrer les date et numéros de page courants, vous devez donc ajouter deux champs spéciaux et déterminer leurs propriétés de <guilabel
>Type</guilabel
> à 0 et 1. Un Spécial avec Type=0 représentera la date et un avec Type=1  le numéro de page. Notez que la propriété du <guilabel
>Text</guilabel
> d'un élément spécial est changée automatiquement. </para>

<para
>Le dernier élément à placer est <guilabel
>Champ calculé</guilabel
> pour le champ <quote
>copies</quote
>. Pour acquérir un sum(copies), positionnez la propriété <guilabel
>Field</guilabel
> du champ calculé sur <quote
>copies</quote
> et <guilabel
>CalculationType</guilabel
> sur 1 (fonction sum). </para>

<para
>Enfin, notre modèle de rapport devrait ressembler à ça. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_complete.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Rapport complet</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect1>



<sect1 id="tut-2">
<title
>Création d'un fichier de données de rapport</title>

<para
>D'une manière générale, les fichiers de données peuvent être créés de plusieurs manières. L'une peut utiliser des tables de transformation xsl pour générer un xml à partir d'un autre document xml (comme un tableur KSpread), une autre utilisera son propre programme pour chercher des données dans une base de données et remplira les champs de données. Dans ce didacticiel, nous le créerons simplement à la main. Le code source pour l'exemple se trouve dans le fichier <filename
>sample1.kud</filename
> ou copié dans l'exemple ci-dessous. </para>

<programlisting
>&lt;?xml version=<quote
>1.0</quote
> encoding=<quote
>UTF-8</quote
>?&gt;

&lt;!DOCTYPE KugarData [
    &lt;!ELEMENT KugarData (Row* )&gt;
    &lt;!ATTLIST KugarData
        Template CDATA #REQUIRED&gt;

    &lt;!ELEMENT Row EMPTY&gt;
    &lt;!ATTLIST Row
        level CDATA #REQUIRED
        title CDATA #REQUIRED
        version CDATA #REQUIRED
        platform CDATA #REQUIRED
        copies CDATA #REQUIRED&gt;
]&gt;

&lt;KugarData Template="sample1.kut"&gt;
    &lt;Row level="0" title="  BRU" version="15.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Caldera Open Linux" version="2.2" platform="x86" copies="3"/&gt;
    &lt;Row level="0" title="  K Desktop" version="1.1.1" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Netscape Communicator" version="4.6" platform="x86" copies="10"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="5.0" platform="x86" copies="11"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="5.1" platform="x86" copies="12"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="5.2" platform="x86" copies="14"/&gt;
    &lt;Row level="0" title="  Redhat Linux" version="6.0" platform="x86" copies="15"/&gt;
    &lt;Row level="0" title="  Star Office" version="5.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Star Office" version="5.1" platform="x86" copies="3"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="3.1" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="3.51" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="4.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Microsoft Windows NT" version="5.0" platform="x86" copies="1"/&gt;
    &lt;Row level="0" title="  Sun Solaris" version="2.5" platform="Sparc" copies="1"/&gt;
&lt;/KugarData&gt;
</programlisting>

</sect1>

<sect1 id="tut-3">
<title
>Génération du rapport</title>

<para
>À ce moment, nous avons un modèle de rapport (<filename
>sample1.kut</filename
>) et un rapport de données (<filename
>sample1.kud</filename
>). </para>
<para
>Pour générer un rapport, saisissez la commande suivante dans un shell : <command
>kugar <option
>-r <replaceable
>sample1.kut</replaceable
></option
> <option
>-d <replaceable
>sample1.kud</replaceable
></option
></command
> </para>

<para
>Ceci ouvrira une fenêtre Kugar avec le rapport généré. <screenshot
> <mediaobject>
<imageobject>
<imagedata fileref="tut_rep_generated.png" format="PNG"/>
</imageobject>
<textobject>
<phrase
>Rapport généré</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

</sect1>

</chapter>
