Tutoriel de création de module

Présentation

Le présent tutoriel consiste à guider pas à pas la construction d'un nouveau Module dans Mediboard. Pour illustrer concrètement le tutoriel, on propose ici la création d'un Module minimaliste de facturation proposant la gestion de factures associées à un objet déjà existant, le Séjour, et constituée de lignes de factures, avec un calcul des taxes et de total.

Analyse technique

Le Framework de Mediboard propose une implémentation MVC (Modèle - Vue - Contrôleur) orientée objet.

Arbre des fichiers

Pour réaliser un Module il est nécessaire de suivre les étapes suivantes :

1. Création du répertoire dPfacturation/ dans le dossier modules/
2. Création des fichiers facture.class.php et factureitem.class.php qui correspondent aux deux classes métiers, respectivement CFacture et CFactureItem : le modèle
3. Création du fichier de configuration setup.php. Ce dernier permet de créer dans la base de donnée nos deux tables. Par la suite il permettra de mettre a jour si besoin nos deux tables (-+facture+- et factureitem).
4. Création du fichier index.php permettant d'ajouter les deux onglets de notre Module et les lier à notre fichier de template.
5. Création des fichiers vw_idx_facture.tpl et vw_idx_factureitem.tpl nécessaires à la présentation des données et de formulaires : les vues
6. Création des fichiers do_facture_aed.php et do_factureitem_aed.php nécessaires aux traitements et la manipulation des données : les contrôleurs

En résumé, l'arbre des fichiers obtenus donne :

• dPfacturation/
  • templates/
    • list_element.tpl
    • vw_idx_facture.tpl
    • vw_idx_factureitem.tpl
  • templates_c/
  • do_facture_aed.php
  • do_factureitem_aed.php
  • facture.class.php
  • factureitem.class.php
  • index.php
  • setup.php
  • vw_idx_facture.php
  • vw_idx_factureitem.php

Modèle métier

Depuis PHP5 et sa couche objet, les applications PHP ont plus qu'evolué, et on ne parle plus de PHP comme un simple langage script pour le web, mais comme un véritable langage orienté objet digne de Java ou C++.

Dans ce Module nous allons mettre en place deux classes CFacture et CFactureItem, incarnant respectivement les factures et les lignes qui les composent, permettant la séparation du code métier PHP et de la partie graphique HTML.

Ce système présente quelques avantages :

1. Pouvoir modifier le code métier sans se soucier du design
2. Créer facilement plusieurs design pour le système
3. Faciliter la maintenance du code
4. Permet de gérer un cache

Le diagramme de classe ci-dessous présente les différentes classes ainsi que les liens entre ces classes.

Création des fichiers du modèle

Les fichiers du modèle représentent les classes métiers : facture.class.php et factureitem.class.php.

Fichier facture.class.php

En plus des méthodes décrites dans la présentation d'une classe métier typique au sein de Médiboard, d'autres fonctions ont été définies :

Obtenir les références indirectes des objets métiers

<?php 
  function getBackRefs() {
      $backRefs = parent::getBackRefs();
      $backRefs["items"] = "CFactureItem facture_id";
      return $backRefs;
  }

Chargement des références indirectes

On charge tous les éléments d'une facture.
Pour cela on charge la liste d'objet des éléments d'une facture.

<?php 
  function loadRefsBack(){
	$item =  new CFactureItem;
	$item->facture_id = $this->_id;
	$this->_ref_items = $item->loadMatchingList();
	$this->_total = 0;
	foreach($this->_ref_items as $_item) {
		$this->_total += $_item->_ttc;
	}
  }

Droit de l'utilisateur

En ce qui concerne les droits d'un utilisateur, la fonction getPerm($permType) permet la vérification des droits en fonction des trois types de droits :

1. PERM_DENY aucune permission
2. PERM_READ permission en lecture
3. PERM_EDIT permission en écriture

Fichier factureitem.class.php

Champs d'aides à la saisie

Lors de la création des éléments d'une facture une aide à la saisie du libellé a été mis en place. Pour cela dans notre classe métier nous devons définir la fonction getHelpedFields() qui permet de lister les champs profitant du système d'aide à la saisie.

<?php 
  function getHelpedFields() {
    return array ( 
      "libelle"   => null,
    );
  }

Analyse des fichiers des contrôleurs

Les contrôleurs permettent de charger les objets qui nous interressent et de les envoyer au moteur de template smarty.

Fichier vw_idx_facture.php

Dans ce fichier, il est nécessaire de charger la facture demandée dans la vue. Dans un premier temps nous récupérons l'identifiant d'une facture si elle a été sélectionnée par l'utilsateur.

<?php 
  $facture_id = mbGetValueFromGet("facture_id");

Ainsi il faut créer une nouvelle instance d'une facture par le mot clé new. Ensuite nous chargeons les propriétés de la facture puis les références de la facture. A partir de là, nous pouvons chargé les informations du patient relatives au Séjour pour une facture donnée.

<?php 
  $facture = new CFacture();
  $facture->load($facture_id);
  if($facture->load($facture_id)) {
	$facture->loadRefs();
	$facture->_ref_sejour->loadRefPatient();
  }

Nous récupérons par la suite la liste de toutes les factures et les références de chacunes d'elles.

<?php 
  $order = "date DESC";
 
  // Récupération de la liste des factures
  $itemFacture = new CFacture;
  $listFacture = $itemFacture->loadList(null,$order);
  foreach($listFacture as &$curr_facture) {
    $curr_facture->loadRefs();
  }

Enfin nous assignons a un objet smarty (-+CSmartyDP+-), les variables PHP déclarées dans le contrôleur nécessaires à la vue.

<?php 
  $smarty = new CSmartyDP();
 
  $smarty->assign("facture", $facture);
  $smarty->assign("listFacture", $listFacture);
  $smarty->display("vw_idx_facture.tpl");

Fichier vw_idx_factureitem.php

Dans ce fichier, il est nécessaire de récupérer les éléments suivants :

1. L'identifiant de la facture.
2. L'identifiant des éléments d'une facture.

Ensuite nous devons charger les objets suivants :

1. L'item d'une aide choisie concernant un libellé.

<?php 
  $libelleItem = new CFactureItem;
  $libelleItem->loadAides($AppUI->user_id);

1. La facture demandée ainsi que les éléments qu'elle contient.

<?php 
  $factureitem = new CFactureitem();
  $factureitem->load($factureitem_id);

1. La facture demandée ainsi que les aides à la saisie disponibles pour l'utilisateur courant.

Enfin nous assignons a un objet smarty (-+CSmartyDP+-), les variables php déclarées dans le contrôleur nécessaires à la vue.

Analyse des fichiers des vues

Fichier vw_idx_facture.tpl

Dans le Framework de Mediboard la Vue de l'implémentation MVC (Modèle - Vue - Controlleur) est réalisé à l'aide de smarty. Comme nous l'avons vu précédemment le contrôleur s'occupe d'envoyer au template vw_idx_facture.tpl les données dont nous avons besoin pour réaliser la vue de notre Onglet. Dans un premier temps nous devons déclarer les fonctions javascript, d'une part pour réaliser la fenêtre de sélection d'un Séjour et d'une autre pour choisir la date à l'aide d'un calendrier. Le code nécessaire est le suivant :

function popObject() {
    var url = new Url;
    url.setModuleAction("system", "object_selector");
    url.addParam("selClass","CSejour");
    url.popup(600, 300, "Object Selector");
  }
  function setObject(oObject){
	var oForm = document.editfacture;
	oForm.sejour_id.value = oObject.id;
	oForm._sejour_view.value = oObject.view;	
	oForm.sejour_id.onchange();
 }
 function pageMain() {
  regFieldCalendar("editfacture", "date");
 }

Les fonctions popObject() et setObject() sont nécessaires pour réaliser la fenêtre de sélection d'un séjour. La première permet de créer un objet sélecteur de la classe Séjour, et la deuxième de modifier la valeur du champ d'un Séjour en affichant la vue de ce séjour. Quant à la fonction pageMain, elle permet de créer un objet de calendrier? qui va nous permettre de sélectionner la date voulue.

En ce qui concerne le code html il est nécessaire de respecter la stratégie d'internationalisation. C'est pourquoi nous devons déclarer l'accès au objet des classes métiers de la manière suivante :

<tr>
     <th>{{mb_label object=$facture field="date"}}</th>
     <td class="date">{{mb_field object=$facture field="date" form="editfacture"}}</td>
  </tr>

Le {{mb_label}} permet de spécifier le label d'un objet, ici le champ datede l'objet $facture. Tandis que le {{mb_field}}, le type du champ a utiliser en fonction de la spécificité renseignée dans la classe métier.

Pour afficher la vue d'une classe métier on peut l'utiliser comme ceci :

{{$facture->_view}}

Pour réaliser la fenêtre "popup" d'une sélection d'un identifiant d'une classe métier, ici de la classe Séjour nous devons procédé comme ceci :

<th>{{mb_label object=$facture field="sejour_id"}}</th>
 <td>
    {{mb_field object=$facture field="sejour_id" hidden=true}}
      {{if $facture->sejour_id}}
    	  <input type="text" size="30" readonly="readonly" ondoublelclick="popObject()" 
           name="_sejour_view" value="{{$facture->_ref_sejour->_view|stripslashes}}" />
      {{else}}
    	  <input type="text" size="30" readonly="readonly" ondoublelclick="popObject()" 
           name="_sejour_view" value="" />
      {{/if}}
         <button type="button" >Rechercher</button>
</td>

Pour afficher le nombre total d'éléments d'une facture il n'est pas nécessaire de le réaliser en php puisque smarty propose le modificateur suivant :

<td>{{$curr_facture->_ref_items|@count}}</td>

Fichier vw_idx_factureitem.tpl

L'Onglet Gestion des éléments permet la création, suppression et modification d'un élément d'une facture. Nous devons renseigner les champs suivants :

1. Le champ libellé qui peut-être rempli à l'aide d'une aide à la saisie déclarée ainsi :

<tr>
    <th>{{mb_label object=$factureitem field="libelle"}} 
    <br />
      <select name="_helpers_libelle" size="1" >
        <option value="">&mdash; Choisir une aide</option>
          {{html_options options=$libelleItem->_aides.libelle.no_enum}}
      </select>
      <button class="new notext" title="Ajouter une aide a la saisie" type="button" >
      </th>
      <td>{{mb_field object=$libelleItem field="libelle"}}</td>
  </tr>

1. Le prix hors-taxe de l'élément.
2. La taxe qui est appliquée a l'élément.

Pour éviter la redondance de code entre les deux fichiers précédents pour l'affichage de la liste des éléments d'une facture nous avons crée un fichier liste_element.tpl gérant cette affichage. Un système de notes utilisateurs? permet de laisser un commentaire sur une facture. Pour insérer l'icone de création ou de visualisation de la note nous devons faire comme ceci :

<div style="float:left;" class="noteDiv CFacture-{{$facture->_id}}">
    <img alt="Ecrire une note" src="images/icons/note_grey.png" />
  </div>

Fonctionnalités

Le résultat fonctionnel de ce Module peut-être consulté sur la page d'aide le concernant.

---