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

Dans le cadre des requêtes sur l'API sur les fiches (type = fiche, type = q-fiche et 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 type = fiche, type = q-fiche et 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 type = fiche
query : variante utilisée pour type = q-fiche
geo : variante utilisée pour 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 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 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).

<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>

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])

<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>

DTD

<!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
   >