====== Datasheets ======

Toute les informations sur l'univers de jeu sont générées à partir de formulaires de données écrits sous l'aspect de fichiers xml. Ils sont généralement édités par le biais de [[fr:georges_editor|Georges Editor]] mais peuvent également être modifiés par un simple éditeur de texte, comme n'importe quel fichier xml(( Cette page est une traduction/adaptation de http://dev.ryzom.com/projects/ryzom/wiki/CreatingABasicForm.)).
Pour se familiariser avec l'aspect de ces données, il est possible d'aller consulter ceux qui sont fournis avec les sources du serveur Ryzom Core dans votre arborescence dans :
<code>code/ryzom/common/data_leveldesign/leveldesign</code>
\\ Les fichiers .dfn et .typ sont dans le sous-répertoire DFN.

===== Les formulaires FORM =====
Un formulaire contient des éléments formels obligatoires.

**Exemple**
<code xml default.sample_config>
<?xml version="1.0"?>
<FORM Version="0.0" State="modified">
        <STRUCT>
                <ATOM Name="TestVal1" Value="1"/>
                <ARRAY Name="TestArray">
                        <ATOM Value="Array Val 1"/>
                        <ATOM Value="Array Val 2"/>
                </ARRAY>
                <ARRAY Name="CoolFilesInfo">
                        <STRUCT>
                                <ATOM Name="ShortName" Value="Tiger Attack"/>
                                <ATOM Name="Ranking" Value="55"/>
                        </STRUCT>
                        <STRUCT>
                                <ATOM Name="ShortName" Value="Crazy Car Jump"/>
                                <ATOM Name="Ranking" Value="40"/>
                        </STRUCT>
                </ARRAY>
                <STRUCT Name="PositionData">
                        <ATOM Name="x" Value="1"/>
                        <ATOM Name="y" Value="1"/>
                        <ATOM Name="z" Value="2"/>
                </STRUCT>
        </STRUCT>
</FORM>
</code>
La première chose à indiquer est le type de fichier :
<code xml>
<?xml version="1.0"?>
</code>
Il faut ensuite,dans l'ordre :
  * un élément <FORM></FORM> qui peut indiquer comme là la version du fichier //Version=""// et l'état //State=""// - OBLIGATOIRE ;
  * un élément <PARENT Filename="" /> - qui indique un fichier de dépendance qui sera traité avant le formulaire lui-même - FACULTATIF ;
  * un élément <STRUCT></STRUCT> - pour organiser les données que le formulaire contient - OBLIGATOIRE ;
  * un élément <COMMENT></COMMENT> - pour donner des indications générales - FACULTATIF ;
  * un élément <LOG></LOG> - pour garder trace des changements - FACULTATIF.

Pour pouvoir créer des formulaires, on va se baser sur un système de parentage et d'héritage.
\\ Un formulaire nécessite un fichier de définition au minimum (.dfn), la première définition chargée se basant sur l'extension du nom du formulaire.
\\ **Exemple**
\\ Si vous créez un formulaire qui s'appelle exemple.config_data, Georges chargera la définition config_date.dfn (et donc toutes les définitions et types qu'elle contient) avant d'exécuter ce formulaire de données.
\\ Commençons donc par voir comment établir les Définitions (fichiers .dfn) et les Types (fichiers .typ).

===== Les deux types de base : .typ et .dfn =====
Il existe deux types essentiels : les .typ (type) et les .dfn (définition).
\\ Les Définitions s'expriment elles-mêmes à l'aide de Types.
<WRAP tip 30% right>Les fichiers .dfn et .typ les plus basiques sont classés dans les sources de Ryzom Core dans :
\\ ///code/ryzom/common/data_leveldesign/leveldesign/DFN/basics//</WRAP>

==== Les Types .typ ====
Les Types sont les plus petits blocs d'information qui puissent être enregistrés dans un formulaire Georges. Avant de pouvoir définir des données plus complexes, il est essentiel de mettre en place les types les plus basiques. Créer de tels documents manuellement permet de mieux en comprendre le fonctionnement.

**Exemple 1 : int.typ, entier**
<code xml int.typ>
<?xml version="1.0"?>
<TYPE Type="SignedInt" UI="EditSpin" Default="0" Min="-9223372036854775808" Max="9223372036854775807">
</TYPE>
</code>

**Exemple 2 : boolean.typ, booléen**
<code xml boolean.typ>
<?xml version="1.0"?>
<TYPE Type="String" UI="NonEditableCombo" Default="false">
  <DEFINITION Label="true" Value="true"/>
  <DEFINITION Label="false" Value="false"/
</TYPE>
</code>

On le voit dans ces deux exemples, le formulaire Georges .typ contient tout d'abord :
<code xml>
<?xml version="1.0"?>
</code>
Puis un élément "TYPE", qui doit être unique, s'ouvrant par <TYPE> et se fermant par </TYPE>.
\\ Il contient lui-même éventuellement un ou plusieurs éléments "DEFINITION", : <DEFINITION Label="" Value=""/>
\\ Il est possible d'ajouter également un élément "COMMENT" pour donner des indications générales et/ou "LOG" pour garder trace des changements.

Les TYPEs peuvent avoir les caractéristiques suivantes :
  * Type - le genre de données que ce type renvoie - OBLIGATOIRE ;
  * UI - le type de widget qui devra être utilisé par un éditeur pour ouvrir ce type - OBLIGATOIRE ;
  * Default - La valeur par défault des éléments qui utiliseront ce type de data ;
  * Min - Pour les valeurs numériques, la valeur minimale valide ;
  * Max - Pour les valeurs numériques, la valeur maximale valide ;
  * Increment - Pour les valeurs numériques l'incrément à laquelle l'UI devra recourir.

Le genre de données renvoyé peut avoir plusieurs valeurs possibles :
  * UnsignedInt (//Entier non signé//)
  * SignedInt (//Entier signé//)
  * Double (//Nombre réel en double précision 64bits//)
  * String (//Chaîne de caractères//)
  * Color (liste de 3 nombres définissant la couleur en mode RVB, par ex "255,255,255")

Les UI reconnues par Georges et pour lesquelles il saura traiter les données sont :
  * Edit (//champ texte court utilisé avec le type __String__//)
  * EditSpin  (//zone numérique avec bouton d'incrément +1 -1 utilisée avec les types __UnsignedInt__, __SignedInt__ et __Double__//)
  * NonEditableCombo (//liste déroulante non éditable utilisée avec le type __String__ pour restreindre les valeurs à une liste prédéfinie//)
  * FileBrowser  (//sélectionneur de nom fichier, utilisé avec le type __String__//
  * BigEdit (//Zone d'édition de textes longs, utilisée en conjonction avec le type __String__//)
  * ColorEdit (//Interface de sélection de couleur pour le type __Color__//)

Chaque élément DEFINITION possède :
  * un "Label", une étiquette. C'est avec cette identifiant que sont faites les comparaisons et les validations ;
  * une "Value", une valeur. C'est ce qui est retourné en réponse à une requête ATOM via l'API dont la valeur correspond à celle de l'étiquette.

Notre fichier .typ de base doit donc ressembler à ça :
<code xml base.typ>
<?xml version="1.0"?>
<TYPE Type="UnsignedInt/SignedInt/Double/String" UI="Edit/EditSpin/NonEditableCombo/FileBrowser/BigEdit/ColorEdit" [Default=""] [Min=""] [Max=""] [Increment=""]>
  <DEFINITION Label="" Value=""/>
  <DEFINITION Label="" Value=""/>
    <COMMENTS></COMMENTS>
  <LOG>Mon Jan 01 00:00:00 0000 (god) Light, please !</LOG>
</TYPE>
</code>

==== Les Définitions .dfn ====
Les Définitions indiquent les STRUCT (structures), ARRAY (tableaux) et ATOM (atomes) utilisables dans les formulaires et le type d'information qu'elles fournissent.

UN fichier .dfn se compose de deux éléments :
  * ELEMENT - Obligatoire, qui décrit les données en ATOM (atome), STRUCT(structure) ou ARRAY(tableau) ;
  * PARENT - Facultatif, qui charge un autre .dfn comme dépendance, ce qui est utile si on utilise souvent les mêmes ATOM(atomes).


**Exemple**
<code xml sample_config.dfn>
<?xml version="1.0"?>
<DFN>
        <ELEMENT Name="TestVal1" Type="Type" Filename="int.typ" Default="0"/>
        <ELEMENT Name="TestVal2" Type="Type" Filename="int.typ" Default="0"/>
        <ELEMENT Name="WriteVal" Type="Type" Filename="int.typ" Default="0" />
        <ELEMENT Name="TestArray" Type="Type" Filename="string.typ" Array="true"/>
        <ELEMENT Name="CoolFilesInfo" Type="Dfn" Filename="coolfilesinfo.dfn" Array="true"/>
        <ELEMENT Name="TestByBracket" Type="Type" Filename="boolean.typ" Array="true"/>
        <ELEMENT Name="PositionData" Type="Dfn" Filename="positiondata.dfn" Array="false" />
</DFN>
</code>

Là encore, le formulaire Georges .dfn contient tout d'abord :
<code xml>
<?xml version="1.0"?>
</code>
Puis on voit <DFN></DFN> qui encadra des <ELEMENTS [...] />

Les ELEMENTS sont les parties les plus sensibles d'une définition car ils varient grandement selon le type de données qu'ils peuvent contenir. Ils contiennent à la base :
  * Name - le nom de cet ELEMENT - OBLIGATOIRE;
  * Filename - le .typ/.dfn auquel se réfère ce type - OBLIGATOIRE;
  * FilenameExt - Par défaut, indiqué comme ".", indique le type d'extension de fichier à traiter - FACULTATIF;
  * Type - le type de cet ELEMENT (voir ci-dessous) - OBLIGATOIRE;
  * Default - la valeur par default de cet élément - FACULTATIF;
  * Array - peut être indiqué "true"/"false" selon que le formulaire donnera plusieurs éléments en tableau ou pas - FACULTATIF/OBLIGATOIRE selon type d'ELEMENT

Le type peut être :
  * Type - pour définir des ATOM, atomes;
  * Dfn - pour définir des STRUCT, structures ou ARRAY, tableaux;
  * DfnPointer - //dont l'usage n'a pu être défini//.

=== Les différents ELEMENT possibles ===
== Pour définir des ATOM, Atomes, les plus simples ==
  * Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
  * Type - son type est "Type" - OBLIGATOIRE;
  * Filename - indiquer le fichier .typ pour définir le type de données que cet ELEMENT utilisera - OBLIGATOIRE;
  * Default - il est possible d'indiquer une valeur par défaut qui remplacera le cas échéant celle indiquée dans le fichier .typ indiqué dans Filename - FACULTATIF.

Une ligne de ce genre donnera donc :
<code xml>
<ELEMENT Name="TestVal1" Type="Type" Filename="int.typ" Default="0"/>
</code>

== Pour définir des STRUCT, Structures ==
  * Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
  * Type - son type est "Dfn" - OBLIGATOIRE;
  * Filename - indiquer le fichier .dfn pour définir les ATOM, atomes qui composeront cet ELEMENT - OBLIGATOIRE;
  * Array="false" - il faut impérativement indiquer à Georges que cela n'est pas un Tableau, mais une Structure - OBLIGATOIRE.

Une ligne de ce genre donnera donc :
<code xml>
<ELEMENT Name="PositionData" Type="Dfn" Filename="positiondata.dfn" Array="false" />
</code>

== Pour définir des ARRAY d'ATOM, Tableaux d'Atomes==
  * Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
  * Type - son type est "Type" - OBLIGATOIRE;
  * Filename - indiquer le fichier .typ pour définir les ATOM, atomes qui composeront cet ELEMENT - OBLIGATOIRE;
  * Array="true" - il faut impérativement indiquer à Georges que c'est un Tableau - OBLIGATOIRE.

Une ligne de ce genre donnera donc :
<code xml>
<ELEMENT Name="TestArray" Type="Type" Filename="string.typ" Array="true"/>
</code>

== Pour définir des ARRAY de STRUCT, Tableaux de Structures ==
  * Name - il faut renseigner un nom, au choix - OBLIGATOIRE;
  * Type - son type est "Dfn" - OBLIGATOIRE;
  * Filename - indiquer le fichier .dfn pour définir les STRUCT, Structures qui composeront cet ELEMENT - OBLIGATOIRE;
  * Array="true" - il faut impérativement indiquer à Georges que c'est un Tableau de Structures - OBLIGATOIRE.

Une ligne de ce genre donnera donc :
<code xml>
<ELEMENT Name="CoolFilesInfo" Type="Dfn" Filename="coolfilesinfo.dfn" Array="true"/>
</code>

===== ATOM, Atomes, ARRAY, Tableaux et STRUCT, Structures =====

Le fichier sample_config.dfn tel qu'il a été mis en place permettra donc au fichier default.sample_config (présenté au début de cette page) de fonctionner car il définit les ATOM, STRUCT et ARRAY que ce Formulaire utilise.
  * les ATOM, Atomes sont les fragments de données individuels les plus petits définissables. Dans le cas où il font partie d'un ARRAY, ils peuvent ne pas avoir de nom propre, d'étiquette mais être désigné du nom de l'ARRAY suivi d'un point puis de leur position dans le tableau. Dans notre exemple, l'ATOM "TestArray.1" a comme valeur "Array Val 1" mais pas de nom explicitement indiqué ;
  * les ARRAY, Tableaux, qui contiennent des listes de données, peuvent concerner des ATOM ("TestArray" dans notre exemple) ou des STRUCT ("CoolFilesInfo") dans notre exemple. Dans ce dernier cas, on extrait les données de l'ARRAY en les désignant du nom de l'ARRAY suivi d'un point puis de l'étiquette (Label) de la STRUCT. "CoolFilesInfo.Ranking" dans notre exemple
  * les STRUCT, Structures, indiquent également leurs valeurs en faisant appel à leur nom suivi d'un point puis de l'étiquette (Label) de l'ATOM dont on souhaite connaitre la valeur. Dans notre exemple, PositionData.x a une valeur de 1

{{tag>outils datasheet}}