====== Fichier fields.xml : définir des variantes sur les champs transmis======

Dans le cadre des requêtes sur l'API sur les fiches ([[serveurscrutari:json:type_fiche|type = fiche]], [[serveurscrutari:json:type_qfiche|type = q-fiche]] et [[serveurscrutari:json:type_geojson|type = geojson]]), il peut être utile de limiter le nombre de champs transmis (pour réduire la taille du fichier JSON résultant) ou de les renommer (par exemple, dans le cas du requête au format GeoJson insérée dans un système qui attend des noms de champs particuliers). Les paramètres //fichefields// et //motclefields// permettent de le faire du côté du client, le fichier de configuration //fields.xml// permet de le faire du côté du serveur.

Effectuer la configuration du côté serveur avec //fields.xml// simplifie la construction de la requête côté client, offre des possibilités de configuration plus vastes et permet de modifier le comportement par défaut.

Le fichier //fields.xml// permet de définir des « variantes ». Chaque variante a un nom, il suffit d'indiquer ce nom dans le paramètre //fieldvariant// disponible dans [[serveurscrutari:json:type_fiche|type = fiche]], [[serveurscrutari:json:type_qfiche|type = q-fiche]] et [[serveurscrutari:json:type_geojson|type = geojson]] pour indiquer la variante à utiliser. Quatre variantes sont définies par défaut dans le logiciel avec les noms suivants :

  * //data// : variante utilisée pour [[serveurscrutari:json:type_fiche|type = fiche]]
  * //query// : variante utilisée pour [[serveurscrutari:json:type_qfiche|type = q-fiche]]
  * //geo// : variante utilisée pour [[serveurscrutari:json:type_qfiche|type = geojson]]
  * //empty// : aucun champ mis à part le code de la fiche ou du mot-clé

Il suffit de définir dans //fields.xml// des variantes avec le nom d'une variante par défaut pour la remplacer.


===== Structure du format XML =====

L'élément racine est l'élément !!<fields>!!. Il peut contenir un nombre illimité d'éléments !!<variant>!!, celui-ci doit posséde un attribut obligatoire, !!@name!!, qui est le nom de la variante. Le nom de la variante doit être un nom « technique », c'est à dire composé uniquement de minuscules non accentuées, de chiffres et du souligné //_//.

Un élément !!variant!! possède les élements suivants :

  * !!<fiche>!! : optionnel et unique, il possède un attribut !!@fields!! destiné à recevoir un contenu identique au paramètre //fichefields// tel que décrit dans [[serveurscrutari:json:fiche_fields|Champs des fiches]]
  * !!<motcle>!! : optionnel et unique, il possède un attribut !!@fields!! destiné à recevoir un contenu identique au paramètre //motclefields// tel que décrit dans [[serveurscrutari:json:motcle_fields|Champs des mots-clés]]
  * !!<alias>!! : en nombre illimité, permet de renommer un champ, voire de construire un champ concaténant des champs existants, il possède trois attributs :
    * !!@name!! : obligatoire, nom du nouveau champ, le nom est libre mais on évitera de le commencer par un souligné « //_// » (//_// préfixe les champs calculés dans ScrutariJs)
    * !!@fields!! : obligatoire, liste des champs composant le nouveau champ, il est similaire à l'attribut //@fields// de l'élément //<fiche>//
    * !!@separator!! : optionnel, il indique le séparateur à utiliser si le nouveau champ est composé de plusieurs valeurs ; peut avoir la valeur spéciale ARRAY et, dans ce cas, la valeur du champ ne sera pas une chaine de caractère mais un tableau de chaines de caractères


==== Exemple ====

L'exemple suivant montre les valeurs des trois variantes définies par défaut (//data//, //query//, //geo//).

<code xml>
<fields>
	<variant name="data">
		<fiche fields="codecorpus,titre,soustitre,complements,year,href,icon"/>
		<motcle fields="labels"/>
	</variant>
	<variant name="query">
		<fiche fields="codecorpus,mtitre,msoustitre,mattrs_all,attrs,mcomplements,year,href,icon"/>
		<motcle fields="mlabels"/>
	</variant>
	<variant name="geo">
		<fiche fields="-codefiche"/>
		<motcle fields="labels"/>
		<alias name="name" fields="titre"/>
		<alias name="url" fields="href"/>
	</variant>
	<variant name="empty">
	</variant>
</fields>
</code>

Un autre exemple avec des alias sur les attributs. Un alias sur un attribut est particulièrement utile si l'attribut est unique : il permet d'accéder à la valeur plus facilement (par exemple, //fiche.website// plutôt que //fiche.attrMap["sct:website"][0]//)

<code xml>
<fields>
	<variant name="export">
		<fiche fields="-codefiche"/>
		<motcle fields="labels"/>
		<alias name="name" fields="titre"/>
		<alias name="description" fields="soustitre"/>
		<alias name="url" fields="href"/>
		<alias name="website" fields="sct:website"/>
		<alias name="thumbnail" fields="sct:thumbnail"/>
	</variant>
</fields>
</code>

===== DTD =====

<code xml>
<!ELEMENT fields (variant?)>

<!ELEMENT variant (fiche?|motcle?|alias*)>
   <!ATTLIST variant name NMTOKEN #REQUIRED>
   
<!ELEMENT fiche EMPTY>
   <!ATTLIST fiche fields NMTOKEN #REQUIRED>

<!ELEMENT motcle EMPTY>
   <!ATTLIST motcle fields NMTOKEN #REQUIRED>
   
<!ELEMENT alias EMPTY>
   <!ATTLIST alias
        name NMTOKEN #REQUIRED
        fields NMTOKEN #REQUIRED
        separator NMTOKEN #IMPLIED
   >

</code>