Feuille de route XML - routines externes

Un article de ScriptdigitalWiki.

Jump to: navigation, search

Feuille de route XML - Fichier XML - Documentation technique - Routines externes


Introduction

Le développement des routines externes d'une feuille de route se fait dans le répertoire /ext/feuillesderoute/, dans un dossier propre au cours. On trouvera un exemple de routines externes commentées dans ce dossier.

Marche à suivre

  • Dans le fichier RoutinesExternes spéficique au cours, il faut créer une méthode.
    • Si cette méthode a le même nom qu'une méthode de RoutinesInternes, c'est la méthode de RoutinesExternes qui sera utilisée.
    • Pour créér un méthode dans RoutinesExternes, il faut simplement faire cela:
function nomFonction ($params)

Si la méthode n'est pas enregistrée dans le fichier xml (dans <donnees> ET dans <element>), cette dernière ne sera pas appellée.

  • Le paramètre $params est un tableau associatif qui contient les clefs suivantes:
'marqueur_nom' => par exemple 'commentaire' qui correspond au marqueur {commentaire}   
'marqueur_id'  => par ex. 'commentaire.commentairedev1' qui correspond au marqueur {commentaire.id}
'marqueur_id_valeur'  => une valeur qui est passé par un formulaire en POST 
et qui correspond au nom de champ d'un marqueur comme {commentaire.id} mais 
remplacera dans le gabarit {commentaire}
'marqueur_routine_ref' => un paramètre de la routine (@ref dans <donnee>), ex. '123-879'
'utilisateur_id'      
'utilisateur_courriel' 
'utilisateur_statut' => le statut de l'utilisateur 
   ('utilisateur_status_formateur', 
    'utilisateur_status_formateur_exploration', 
    'utilisateur_status_formateur')  
'cours_id'             
'element_titre'

Note: les valeurs des clefs marqueur_id_valeur, marqueur_routine_ref, marqueur_id doivent être vérifiées car même si ces clefs sont toujous présentes, elles peuvent avoir pour valeur null si dans le premier cas, il n'y a pas eu de soumission de formulaire, et si dans le second cas, il n'y a pas d'attribut ref dans la balise <champ> dans la balise <element> du fichier XML. Enfin, dans le troisièreme cas, la valeur sera aussi null si il n'y a pas d'attribut id dans la balise <champ> dans la balise <element> du fichier XML.


  • La routine peut retourner trois valeurs.
routine valide => retourne un tableau comme par exemple:
    return array ('valide' => true, 'marqueur_valeur' => $date);
routine invalide avec erreurs => retourne un tableau comme par ex. 
    return array ('valide' => false, 'erreur' => 'date invalide');
L'erreur sera aggrégée dans la macro $MACRO['feuillederoute_msgErreur'] 
et utilisera le gabarit des erreurs définis dans le fichier XML de la 
feuille de route.
routine invalide sans erreurs => par ex soit
return array ('valide' => false, 'erreur' => ''); ou return false
  • Quand la routine est valide, le marqueur défini dans 'marqueur_nom' reçu en paramètre sera remplacé par 'marqueur_valeur' qui est retourné par la routine.