Formater des documents marcxml

1) Localisation des plugins dans les rubriques

Les plugins pour le formatage des notices marcxml sont localisés dans le registre dans plugins/catalogue/marcxml/formatage/nom_de_l_objet

Le formatage est utilisé dans plusieurs cas :

> Générer les accès
> Générer les tris
> Générer les liens explicites
> Formater les données retournées aux champs autocomplete
> Formater des notices et des listes de notices pour affichage.

a. générer les accès et les tris

On utilise un plugin (généralement "formate_plugins") par accès.
Puis dans le sous-répertoire "main" on créera des plugins correspondant à des regroupements d'accès.
Par exemple, on aura le plugin "defaut" utilisé la plupart du temps :
+ chemin_fichier => catalogue/marcxml
+ nom_fonction => formate_plugins_array
+ parametres
     + plugins
          + a_auteurs =>
               + nom_plugin => catalogue/marcxml/formatage/biblio/acces/auteurs
          + a_titres
               + nom_plugin => catalogue/marcxml/formatage/biblio/acces/titre
          + a_tousmots
               + nom_plugin => catalogue/marcxml/formatage/biblio/acces/tousmots

b. générer les liens explicites

Génère une chaine de caractères de la forme a:toto|b:tutu qui indique comment générer un champ de lien
Par exemple, dans "auteur/liens_explicites", pour générer le champ de lien 700 des notices biblio, on crée "biblio_700":

+ chemin_fichier => catalogue/marcxml
+ nom_fonction => get_datafields
+ parametres
     + champs
          + 01 - 200
               + sous-champs
                    + 01 - a nom
                         + apres => |
                         + avant => a:
                         + code => a
                    + 02 - b prénom
                         + apres => |
                         + avant => b:
                         + code => b
               + tag => 200

c. formater les données retournées aux champs autocomplete

voir la note sur les champs autocomplete

d. formater des notices et des listes de notices pour affichage

Plusieurs répertoires sont concernés :
> notice : les plugins servant à générer un affichage de notice. P-ê de type isbd, tableau, public...
> elem_notice : des plugins pour générer des blocs de la notice (qui seront assemblés dans les plugins de notice)
> liste : pour les liste de notices : formate la liste met des éléments entre les notices et aussi avant et après la liste
> formats_liste : Définit un format, en associant un plugin de formatage de notice, un plugin de formatage de liste (optionnel) et un intitulé.
> listes_format_notices : des listes de formats de notices
> listes_formats_listes : des listes de formats de listes

2) Utilisation des plugins

get_datafields_node_list

/**
 * plugin_catalogue_marcxml_get_datafields_nodelist()
 * 
 * 
 * Ce plugin retourne un tableau (!! PAS un nodelist) de tous les champs (DomNode) d'une notice présentant certains critères :
 * le nom du champ (200, 700, 464...)
 * la présence de certains sous-champs ($a, $b...)
 * La valeur des sous-champs
 * la position du champ ou du ss-champ dans la liste
 * NOTE : c'est une disjonction. Il suffit que la condition soit remplie pour UN sous sous-champ, et le champ sera validé // p-ê à modifier plus tard
 * La notice peut être fournie soit sous forme d'objet DomXml soit directement tvs_marcxml
 * 
 * @param array $parametres
 * 
 * @param ["notice"] => notice en marcxml. (inutile si objet tvs_marcxml fourni)
 * @param ["tvs_marcxml"] => objet tvs_marcxml. Si non fourni, généré à partir de la notice (DomXml)
 * 
 * @param ["champs"] => liste des champs à extraire
 * @param ["champs"][XXX]["tag"]=> 1 des champs
 * @param ["champs"][XXX]["idx"]=> position si plusieurs champs identiques : à partir de 1 ou "last()" pour le dernier
 * @param ["champs"][XXX]["plugin_formate"]=> Un plugin pour formater le champ. Le texte sera envoyé dans l'attribut [texte] et récupéré également dans [texte]
 * @param ["champs"][XXX]["sous-champs"]=> sous-champs devant être présents pour extraire ce champ
 * @param ["champs"][XXX]["sous-champs"][YYY]["code"]=> 1 des sous-champs
 * @param ["champs"][XXX]["sous-champs"][YYY]["valeur"]=> valeur que doit prendre le sous-champ. Si vide, on accède n'importe quelle valeur du moement que le ss-champ est présent
 * @param ["champs"][XXX]["sous-champs"][YYY]["idx"]=> position si plusieurs ss-champs identiques : à partir de 1 ou "last()" pour le dernier
 * @param ["champs"][XXX]["sous-champs"][YYY]["plugin_formate"]=> Un plugin pour formater le ss-champ. Le texte sera envoyé dans l'attribut [texte] et récupéré également dans [texte]
 * 
 * @return $retour => liste (array) des champs (array)
 */

get_datafields

/**
 * plugin_catalogue_marcxml_get_datafields()
 * 
 * Ce plugin retourne des champs et sous-champs formatés sous forme de string.
 * Le formatage (champs/sous champs à récupérer et la ponctuation, séparateurs...) est indiqué dans l'attribut [champs]
 * La notice peut être fournie soit sous forme d'objet DomXml soit directement tvs_marcxml
 * 
 * @param array $parametres
 * 
 * @param ["notice"] => notice en marcxml. (inutile si objet tvs_marcxml fourni)
 * @param ["tvs_marcxml"] => objet tvs_marcxml. Si non fourni, généré à partir de la notice (DomXml)
 * 
 * @param ["champs"] => liste des champs à extraire
 * @param ["champs"][XXX]["tag"]=> 1 des champs
 * @param ["champs"][XXX]["idx"]=> position du champ dans la liste ou last()
 * @param ["champs"][XXX][avant|avant_verif|apres|plugin_formate] => chaines de caractères à placer avant, avant (si déjà qqchse avant) ou après le contenu du champ
 * @param ["champs"][XXX]["sous-champs"]=> sous-champs à extraire pour ce champ
 * @param ["champs"][XXX]["sous-champs"][YYY]["code"]=> 1 des sous-champs
 * @param ["champs"][XXX]["sous-champs"][YYY]["idx"]=> position du ss-champ dans la liste ou last()
 * @param ["champs"][XXX]["sous-champs"][YYY]["valeur"]=> Valeur requise pour un sous-champ
 * @param ["champs"][XXX]["sous-champs"][YYY][avant|avant_verif|apres|plugin_formate] => chaines de caractères à placer avant, avant (si déjà qqchse avant) ou après le contenu du ss-champ
 *
 * @return $retour["resultat"]["texte"] => texte trouvé
 */

get_datafields_array

/**
 * plugin_catalogue_marcxml_get_datafields_array()
 * 
 * Ce plugin retourne une liste de champs (datafields) comme get_data_fields, mais il le fait sous forme de tableau :
 * exemple :
 * [600]
 *     [0] => "toto : tutu : titi"
 *     [1] => "popo : pupu : pipi"
 * [606]
 *     [0] => ...
 * 
 * @param array $parametres
 * @param ["notice"] => notice en marcxml
 * @param ["tvs_marcxml"] => objet tvs_marcxml. Si non fourni, généré à partir de la notice (DomXml)
 * 
 * @param ["champs"] => liste des champs à extraire
 * @param ["champs"][XXX]["tag"]=> 1 des champs
 * @param ["champs"][XXX]["idx"]=> position si plusieurs champs identiques : à partir de 1 ou "last()" pour le dernier
 * @param ["champs"][XXX][avant|avant_verif|apres] => chaines de caractères à placer avant, avant (si déjà qqchse avant) ou après le contenu du champ
 * @param ["champs"][XXX]["sous-champs"]=> sous-champs à extraire pour ce champ
 * @param ["champs"][XXX]["sous-champs"][YYY]["code"]=> 1 des sous-champs
 * @param ["champs"][XXX]["sous-champs"][YYY]["idx"]=> position du ss-champ dans la liste ou last()
 * @param ["champs"][XXX]["sous-champs"][YYY]["valeur"]=> Valeur requise pour un sous-champ
 * @param ["champs"][XXX]["sous-champs"][YYY][avant|avant_verif|apres] => chaines de caractères à placer avant, avant (si déjà qqchse avant) ou après le contenu du ss-champ
 * @param ["champs"][XXX]["sous-champs"][YYY]["plugin_formate"]=> Un plugin pour formater le ss-champ. Le texte sera envoyé dans l'attribut [texte] et récupéré également dans [texte]
 * 
 * @return $retour["resultat"]["texte"] => texte trouvé
 */

formate_plugins

/**
 * plugin_catalogue_marcxml_formate_plugins()
 * 
 * Ce plugin permet de formater une liste de plugins
 * 
 * Il appelle successicement les plugins comme ceci :
 * [notice]<=([notice])
 * 
 * ATTENTION : à la base ce plugin fonctionnait avec les plugin "get_datafields_xxx" qui attendaient le paramètre en [notice] et retournaient le résultat en [notice]
 * Mais il peut aussi fonctionner avec d'autres plugins qui ont une autre signature. Dans ce cas, il faut utiliser des alias
 * 
 * 
 * @param mixed $parametres
 * @param["notice"] => notice XML de base (à passer à tous les autres plugins)
 * @param["plugins"][0,1,2...][nom_plugin]
 *                            [parametres] // parametres du plugin
 *                            [avant]
 *                            [apres]
 *                            [avant_verif]
 * 
 * pour chaque plugin :
 *      $tmp[texte] = plugin([notice])
 * 
 * @return [texte] => le texte formaté
 */

formate_plugins_array

/**
 * plugin_catalogue_marcxml_formate_plugins_array()
 *  
 * Ce plugin retourne un tableau associatif, chaque élément du tableau étant généré par un autre plugin
 * Il appelle successicement les plugins comme ceci :
 * [notice]<=([notice])
 * 
 * ATTENTION : à la base ce plugin fonctionnait avec les plugin "get_datafields_xxx" qui attendaient le paramètre en [notice] et retournaient le résultat en [notice]
 * Mais il peut aussi fonctionner avec d'autres plugins qui ont une autre signature. Dans ce cas, il faut utiliser des alias
 * 
 * @param mixed $parametres
 * @param [notice]
 * @param [plugins]
 * @param       [toto] => [nom_plugin]
 * @param                 [parametres]   
 * @param [force_retour] : si 1, on retourne qqchse, même si 1 ou plusieurs plugins ont retourné des erreurs. Sinon, on propage l'erreur
 * 
 * @return array => retourne directement le tableau à la racine
 */

formate_array

/**
 * plugin_catalogue_marcxml_formate_array()
 * 
 * Formate une array. retourne une chaine de caractères
 * 
 * @param mixed $parametres
 * @param [avant]
 * @param [apres]
 * @param [avant_element]
 * @param [avant_element_verif]
 * @param [apres_element]
 * @param [tableau] => l'array à formater
 * 
 * @return [texte] => chaine formatée
 */

get_colonnes

/**
 * plugin_catalogue_marcxml_get_colonnes()
 * 
 * Ce plugin permet de mettre en forme des informations fournies sous forme de tableau. Il est typiquement utilisé pour
 * mettre en forme des infos extraites d'une base de données (ligne de résultat) en particulier les tables obj_xxx_acces
 * 
 * @param array $parametres
 * @param [tableau] => le tableau contenant les colonnes à formater
 * @param [colonnes][0,1,2...][nom_colonne | avant | apres | avant_verif] => infos contenant le formatage
 * 
 * 
 * @return [texte] => le texte formaté
 */

get_colonnes_array

/**
 * plugin_catalogue_marcxml_get_colonnes_array()
 * 
 * Comme get_colonnes, mais retourne le résultat sous forme d'array.
 * Fait correspondre la colonne [nom_colonne] au champ [nom_champ] du tableau
 * 
 * @param array $parametres
 * @param [tableau] => le tableau contenant les colonnes à formater
 * @param [colonnes][0,1,2...][nom_colonne | nom_champ | avant | apres ] => infos contenant le formatage
 * 
 * 
 * @return [texte] => ATTENTION : un tableau
 */