## Ecrire des Rapports (Scripts)

Cette page donne les grandes lignes, à ceux qui veulent se lancer dans l'écriture de rapports (scripts) pour GenJ, à savoir :

1. Les bases
2. Les propriétés et le support international
3. Les options
4. Rajouter encore plus de code Java
5. Obtenir des données (Part 1): Utilisation des méthodes sur les objets
6. Obtenir des données (Part 2): Utilisation des étiquettes et des propriétés

## Les bases

Un rapport GenJ est un Java-type qui étend le type abstrait genj.report.Report. Écrire votre propre fonction commence par définir votre propre classe dans un fichier source qui sera placé dans le sous-répertoire « reports » (son nom doit débuter avec Report*).

Supposons que nous voulions écrire un rapport test nommé « Test ». D'abord, créons un fichier texte appelé ReportTest.java dans ./reports. Ensuite compilons-le en lançant le script de compilation dans le même répertoire : rcompile.*(bat, sh, cmd). Ce script lance javac (le compilateur java). Le résultat final est un fichier appelé ReportTest.class que GenJ peut charger et exécuter lorsqu'il sera sélectionné dans la Visualisation des Rapports.

Regardons le fichier exemple ReportTest.java. Il contient une définition de classe publique qui est conforme à la finalité du Rapport (extension de Rapport). Une partie de cette finalité est d'implanter un public void start(Object context) qui est le point d'entrée dans le Rapport. Nous pouvons utiliser toutes les méthodes fournies par le paquetage Report - (ici nous utilisons simplement la méthode « println »). println() envoie du texte dans un élément graphique (un "widget") que l'utilisateur peut voir quand il exécute le rapport.

import genj.gedcom.*;
import genj.report.*;
import genj.report.Report;
public class ReportTest extends Report {
/**
* the 'main' method
*/
public void start(Object context) {
println("Salut la terre !");
}
}

Maintenant, nous voulons êtres sûrs que ce rapport s'intègre parfaitement dans la Visualisation des Rapports avec son nom, des informations de base, la référence à l'auteur, son numéro de version. Pour arriver à cela, nous créons un fichier ReportTest.properties dans le même répertoire et le remplissons avec l'information nécessaire, ce qui va donner ceci :

# File: ReportTest.properties
# Voici les ressources de texte pour ReportTest
name = A Simple Test
name.fr = Un simple Test
info = This is a test report to start in Report writing for GenJ
info.fr = Ceci est un rapport de Test pour démarrer l'écriture de rapports pour GenJ
author = Daniel Durand

Le rapport apparaît correctement maintenant mais nous devons ajouter quelque chose au démarrage pour qu'il soit utilisable par n'importe quel utilisateur. Par défaut, les rapports peuvent être lancés uniquement dans un contexte Gedcom - ceci implique que l'argument de démarrage () doit être une instance du type Java Gedcom. Nous le permettons avec context intanceofGedcom. Une utilisation simple serait de rapporter le nombre d'individus dans l'objet Gedcom. Nous le faisons en modifiant la méthode de départ ainsi :

public void start(Object context) {
// nous savons que le contexte est une instance de Gedcom par defaut
Gedcom gedcom = (Gedcom)context;
// Comptons le nombre d'individus
int count = gedcom.getEntities(Gedcom.INDI).size()
// ... et publions-le
println("Gedcom "+gedcom.getName()+" contains "+count+" individuals");
}

L'API pour genj.report Report et genj.gedcom.Gedcom GenJ contient plusieurs méthodes pour accéder et présenter l'information existante (voir les Javadocs GenJ pour en savoir plus).

## Propriétés et internationalisation

Dans le but de permettre son internationalisation, votre rapport NE doit PAS imprimer des chaînes fixes directement. Au lieu de cela, il doit utiliser un fichier de propriétés pour définir les chaînes à imprimer, et ensuite les obtenir à partir de ce fichier. Ainsi, le ficher de propriétés pourra être traduit dans d'autres langages. Par exemple, n'écrivez pas cela : `println("Birth Date is")`;
Faites plutôt :

println(i18n("BirthDateIs"));
et écrivez des lignes semblables à celles-ci dans votre fichier de propriétés :
BirthDateIs = Birth Date is
BirthDateIs.fr = La Date de Naissance est

## Options

Chaque rapport a un choix d'options, que vous pouvez facilement utiliser, en créant des variables de classes publiques dans votre classe de rapport et des propriétés dans votre fichier de propriétés. Par exemple, laissez votre rapport générer du texte par défaut, mais aussi la possibilité de créer de l'HTML, et vous permettrez aux utilisateurs de préciser eux-mêmes ce qu'ils veulent. Commencez en créant une nouvelle variable publique dans votre classe de rapport java :

public boolean generateHTML = true ;
et ensuite ajoutez du texte dans votre fichier de propriétés :
generateHTML = Voulez-vous générer une sortie HTML ?
chargez votre rapport, et examinez l'onglet des options pour voir le résultat.

Pour créer un menu déroulant avec plusieurs choix, utilisez les variables publiques :

public int outputFormat = 0;
public static String[] outputFormats = { "Soundex", "Metahphone", "Double Metaphone", "NYSIIS", "Phonex" };
et ceci dans votre fichier de propriétés :
outputFormat=Output format
outputFormat.de=Ausgabe-Format
Il y a quelques options plus complexes disponibles. Jetez un oeil sur ReportEvent.java pour plus d'exemples.

## Charger plus de code Java

Tout le code java dans le répertoire des rapports est compilé par le script de compilation, et tout est chargé dans GenJ. Ainsi, si vous souhaitez utiliser d'autres classes dans votre rapport, vous avez juste à copier les fichiers java ou les fichiers de classes dans votre rapport, et ils seront chargés en attendant que vous les utilisiez.

Par exemple, si vous souhaitez utiliser une classe DMSoundex, placez juste le fichier DMSoundex.java dans le répertoire des rapports et lancez rcompile. Il sera alors disponible pour vous, mais n'apparaîtra pas comme un rapport, car il n'est pas une sous-classe de genj.report.Report.

## Obtenir des données (Part 1): Utiliser les méthodes objets

Les objets qui stockent l'information depuis le fichier GEDCOM possèdent des méthodes pour accéder aux noms, dates, enfants et parents (mais pas aussi nombreuses que vous pourriez le souhaiter). Quelques exemples figurent ci-dessous :

//Méthodes disponibles dans la classe Indi (Individuals)
//Ce n'est pas une liste complète ! Juste assez pour que vous démarriez.
String getBirthAsString() // Note: Ceci est une DATE de naissance (non un objet complet)
String getDeathAsString() // Note: Ceci est une DATE de décès (non un objet complet)
String getName()
String getFirstName()
String getLastName()
Fam getFamc() // Obtenir une famille dont cette personne est l'enfant
Indi getFather()
Indi getMother
Indi[] getChildren()
//Méthodes disponibles pour la classe Fam (Families)
//Ce n'est pas une liste complète ! Juste assez pour que vous démarriez.
Indi getChild(int which)
Indi[] getChildren()
Indi getHusband()
Indi getWife()
Vous pouvez aussi examiner la PropertyDate class, et les méthodes qui retournent ces objets depuis d'autres classes.

## Obtenir des données (Part 2): Utiliser les tags et les propriétés

Beaucoup de données dans un fichier GEDCOM sont disponibles à partir de tags, plutôt que par des méthodes ou des objets. Par exemple, pour obtenir des informations sur la naturalisation d'une personne, vous n'avez pas à écrire ceci: `indi.getNaturalization()`. A la place, vous devriez écrire ceci :

PropertyEvent naturalization = (PropertyEvent)indi.getProperty(new TagPath("INDI:NATU")) ;
Ou vous pouvez obtenir plus d'informations avec un appel semblable à celui-ci :
PropertyDate prop = (PropertyDate)indi.getProperty(new TagPath("INDI:NATU:DATE"));
String dateOfNaturalization = prop.getValue() ;
Obtenir les données des notes est un peu plus complexe. Le code suivant retournera des notes d'événements comme une chaîne. Vous pouvez l'appeler ainsi :
// Exemple d'utilisation
PropertyEvent immigration = (PropertyEvent)indi.getProperty(new TagPath("INDI:IMMI")) ;
String note = getNote(immigration) ;
if (note==null) note = i18n("noNote") ;
println(note) ;
// voici le code:
private String getNote(PropertyEvent e) {
if (e==null) return null ;
MultiLineProperty prop = checkNote(e.getProperty("NOTE")) ;
if (prop==null) return null ;
return prop.getLinesValue() ;
}
/**
* Cherche une propriété de NOTE et si possible
* retourne la MultiLineProperty pour accéder à sa valeur
*/
MultiLineProperty checkNote(Property prop) {
if (prop==null) return null ;
// Ca doit être une 'NOTE'
if (!prop.getTag().equals("NOTE"))
return null;
// voit si la propriété est une référence de note
if (prop instanceof PropertyNote) {
// .. va à la cible référence
prop = ((PropertyNote)prop).getTarget();
}
// voit si nous avons une propriété multilignes contenant
// le texte de la note maintenant
if (prop instanceof MultiLineProperty )
return (MultiLineProperty)prop;
// pas de proposition
return null;
}

Pour utiliser ces chaînes TagPath, vous avez besoin de connaître quels codes de quatre lettres font partie du standard GEDCOM. voici deux liens avec plus d'information pour vous aider :
http://www.math.clemson.edu/~rsimms/genealogy/ll/gedcom55.pdf
http://www.gendex.com/gedcom55/55gcappa.htm

Voci un tableau memento des tags les plus communs :
Haut niveau : INDI (individu), FAM (Famille)
Evénements : BIRT (Naissance), DEAT (Décès), IMMI (Immigration),NATU (Naturalisation), BAPT (Baptême)
Autres : CHIL (Enfant), FAMC (Famille de l'enfant), HUSB (Epoux), WIFE (Epouse)
Composants: ADDR (adresse), DATE (date), NOTE (Note), PLAC (lieu)

La "Fenêtre d'Edition" dans sa fonction Editeur Gedcom (à l'inverse de l'Editeur Standard), montre exactement quels tags ont des données pour quelles entités, et c'est un bon moyen pour comprendre la structure et les éléments de GEDCOM.

Vous pouvez examiner le code source du rapports des Evenements pour voir comment ces Tags sont utilisés. Aussi, vous pouvez examiner le fichier GEDCOM lui-même pour voir quels tags sont des sous-tags d'autres tags.