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

All information about the game universe is generated from data forms, written as xml files. They are usually edited with the [[georges_editor|Georges Editor]] but can also be edited by a simple text editor, just like any xml file.(This page is a translation/adaptation of http://dev.ryzom.com/projects/ryzom/wiki/CreatingABasicForm.)).
To familiarize yourself with the appearance of this data, it is possible to go to those provided with the Ryzom Core server sources in your tree(in):
<code>code/ryzom/common/data_leveldesign/leveldesign</code>
\\ The .dfn and .typ files are in the DFN subdirectory.

===== Forms FORM =====
A form contains mandatory formal elements.

**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>
The first thing to indicate is the file type:
<code xml>
<?xml version="1.0"?>
</code>
Then, in order:
   * a <FORM></FORM> element which can indicate like the version of the file //Version="// and the state //State=""//-MANDATORY;
   * a <PARENT Filename = "" /> element - which indicates a dependency file that will be processed before the form itself - OPTIONAL;
   * a <STRUCT></STRUCT> element - to organize the data that the form contains - MANDATORY;
   * a <COMMENT></COMMENT> element - to give general indications - OPTIONAL;
   * a <LOG></LOG> element - to keep track of changes - OPTIONAL.

In order to create forms, we will rely on a system of parenting and inheritance.
\\ A form requires a minimum definition file (.dfn), the first definition loaded based on the name extension of the form.
\\ **Example**
\\ If you create a form named example.config_data, Georges Editor will load the config_date.dfn definition(and therefore all the definitions and types it contains) before running this data form.
\\ So let's start by looking at how to define Definitions(.dfn files) and Types(.typ files).

===== The two basic types: .typ and .dfn =====
There are two basic types: .typ (type) and .dfn (definition).
\\ Definitions express themselves using Types.
<WRAP tip 30% right> The most basic .dfn and .typ files are categorized in the Ryzom Core sources in:
\\ ///code/ryzom/common/data_leveldesign/leveldesign/DFN/basics//</WRAP>

==== The Types .typ ====
Types are the smallest blocks of information that can be saved in a Georges form. Before defining more complex data, it is essential to set up the most basic types. Creating such documents manually makes it easier to understand how they work.

**Exemple 1 : int.typ, whole**
<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, boolean**
<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>

As you can see in these two examples, the Georges .typ form contains:
<code xml>
<?xml version="1.0"?>
</code>
Then a "TYPE" element, which must be unique, opening with <TYPE> and closing with </TYPE>.
\\ It may contain one or more "DEFINITION" elements:<DEFINITION Label="" Value=""/>
\\ It is also possible to add a "COMMENT" element to give general indications and/or "LOG" to keep track of the changes.

TYPE's may have the following characteristics:
   * Type - the kind of data that this type returns - MANDATORY;
   * UI - the type of widget that should be used by a publisher to open this type - MANDATORY;
   * Default - The default value for items that will use this type of data;
   * Min - For numeric values, the minimum value is valid;
   * Max - For numeric values, the maximum valid value;
   * Increment - For numeric values, the increment to which the UI will have to resort.

The returned data type can have several possible values:
  * UnsignedInt (//unsigned integer//)
  * SignedInt (//Signed Integer//)
  * Double (//Actual number in double precision 64bits//)
  * String (//String//)
  * Color (list of 3 numbers defining color in RGB mode, eg "255,255,255")

The IU recognized by Georges(and for which it will be able to process the data) are:
  * Edit (//short text field used with type__String__//)
  * EditSpin (//numeric field with increment button +1 -1 used with the types __UnsignedInt__, __SignedInt__ and __Double__//)
  * NonEditableCombo (//non-editable drop-down list used with type __String__ to restrict values ​​to a predefined list//)
  * FileBrowser (//file name selector, used with type __String__//
  * BigEdit (//Long text edit box, used in conjunction with type __String__//)
  * ColorEdit (//Color selection interface for type __Color__//)

Each DEFINITION element has:
   * a "etiket", a label. It is with this identifier that comparisons and validations are made;
   * a "Value", an value. This is what is returned in response to an ATOM request via the API whose value matches that of the label.

So our basic .typ file should look like this:
<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>

==== Definitions .dfn ====
Definitions indicate the STRUCT(structures), ARRAY(arrays) and ATOM(atoms) that can be used in forms and the type of information they provide.

A .dfn file consists of two elements:
   * ELEMENT - Mandatory, which describes the data in ATOM(atom), STRUCT(structure) or ARRAY(table);
   * PARENT - Optional, which loads another .dfn as a dependency, which is useful if you often use the same ATOM(atoms).
**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>

Again, the Georges .dfn form contains:
<code xml>
<?xml version="1.0"?>
</code>
Then we see <DFN></DFN> which frames <ELEMENTS [...] />

ELEMENTS are the most sensitive parts of a definition because they vary greatly depending on the type of data they can contain. They contain:
   * Name - the name of this ELEMENT - COMPULSORY;
   * Filename - the .typ/.dfn to which this type refers - MANDATORY;
   * FilenameExt - Default, indicated as ".", Indicates the type of file extension to be processed - OPTIONAL;
   * Type - the type of this ELEMENT(see below) - MANDATORY;
   * Default - the default value of this element - OPTIONAL;
   * Array - can be indicated "true"/"false" depending on whether the form will give more than one element in an array or not - OPTIONAL/MANDATORY according to ELEMENT type

The type can be:
   * Type - to define ATOM, atoms;
   * Dfn - to define STRUCT, structures or ARRAY, arrays;
   * DfnPointer - //whose usage could not be defined//.

=== The different possible ELEMENT's ===
== To define ATOM, Atoms, the simplest ==
   * Name - you must fill in a name, at your choice - MANDATORY;
   * Type - it's type is "Type" - MANDATORY;
   * Filename - specify the .typ file to define the data type that this ELEMENT will use - MANDATORY;
   * Default - it is possible to specify a default value that will replace the one specified in the .typ file specified in Filename - OPTIONAL.

A line of this kind will therefore give:
<code xml>
<ELEMENT Name="TestVal1" Type="Type" Filename="int.typ" Default="0"/>
</code>

== To define STRUCT, Structures ==
   * Name - you must fill in a name, at your choice - MANDATORY;
   * Type - its type is "Dfn" - MANDATORY;
   * Filename - specify the .dfn file to define the ATOM, atoms that will make up this - COMPULSORY ELEMENT;
   * Array = "false" - it is imperative to tell Georges that this is not a Table, but a Structure - MANDATORY.

A line of this kind will therefore give:
<code xml>
<ELEMENT Name="PositionData" Type="Dfn" Filename="positiondata.dfn" Array="false" />
</code>

== To define ATOM ARRAYs, Atom Tables ==
   * Name - you must fill in a name, at your choice - MANDATORY;
   * Type - it's type is "Type" - MANDATORY;
   * Filename - specify the .typ file to define the ATOMs, atoms that will make up this - MANDATORY ELEMENT;
   * Array = "true" - it is imperative to indicate to Georges that it is a Table - MANDATORY.

A line of this kind will therefore give:
<code xml>
<ELEMENT Name="TestArray" Type="Type" Filename="string.typ" Array="true"/>
</code>

== To define STRUCT ARRAYs, Structural Tables ==
   * Name - you must fill in a name, at your choice - MANDATORY;
   * Type - it's type is "Dfn" - MANDATORY;
   * Filename - indicate the .dfn file to define the STRUCT, Structures that will make up this ELEMENT - COMPULSORY;
   * Array = "true" - it is imperative to indicate to Georges that it is a Table of Structures - MANDATORY.

A line of this kind will therefore give:
<code xml>
<ELEMENT Name="CoolFilesInfo" Type="Dfn" Filename="coolfilesinfo.dfn" Array="true"/>
</code>

===== ATOM, Atomes, ARRAY, Tables and STRUCT, Structures =====

The file "sample_config.dfn"(as it was set up) will allow the "default.sample_config" file(shown at the beginning of this page) to work because it defines the ATOM, STRUCT and ARRAY that this Form uses.
  * ATOMs, Atomes are the smallest individual data fragments that can be defined. If they are part of an ARRAY, they may have no proper name, label but be designated by the name of ARRAY followed by a period then their position in the table. In our example, the ATOM "TestArray.1" has the value "Array Val 1" but no name explicitly specified;
  * ARRAY, Tables, which contain lists of data, can concern ATOM("TestArray" in our example) or STRUCT("CoolFilesInfo") in our example. In the latter case, the data of the ARRAY are extracted by designating them from the ARRAY name followed by a point and then the label(Label) of the STRUCT. "CoolFilesInfo.Ranking" in our example
  * The STRUCT, Structures, also indicate their values ​​using their name followed by a point and then the label of the ATOM whose value we want to know. In our example, "PositionData.x" has a value of "1".

{{tag>utilities datasheet}}