On appelle correspondance simple, une correspondance où un record est mappé sur une seule table. Pour déclarer la table sur laquelle reposera le DAO, on utilise la balise <primarytable>, avec les attributs suivants :

• name : alias donné à la table et qui sera utilisé dans les requêtes
• realname (facultatif) : nom réel de la table dans la base de données. Si cet attribut n'est pas précisé, il prend la même valeur que l'attribut name. Dans ce cas name doit être le nom réel de la table.
• primarykey indique la clé primaire. Vous pouvez indiquer plusieurs champs en les séparant par un espace ou une virgule.

  <datasources>
      <primarytable name="p" realname="products" primarykey="id_product" />
  </datasources>

On déclare ici que le record sera basé sur la table "products", qui a pour alias "p", et dont la clé primaire est "id_product".

Il n'y a toujours qu'une seule table "primaire" dans un DAO (donc une seule balise <primarytable>). Vous verrez que l'on peut indiquer des tables annexes (étrangères) plus loin.

Ensuite, il faut déclarer la correspondance propriété - champs.

La section <record> déclare les propriétés d'un objet record (enregistrement). Chaque propriété correspond à l'un des champs de la table primaire, ou l'un de ceux des tables étrangères comme vous le verrez plus loin. Bien sûr, vous n'êtes pas obligés de déclarer une propriété pour tous les champs existants. On peut ainsi faire plusieurs DAO qui travaillent sur une même table mais qui sont destinés à des usages différents. Par exemple faire un DAO spécifique pour récupérer des listes légères d'enregistrement (on ne déclarera que les propriétés essentielles), et un autre pour les gérer de manière complète (on y indiquera tous les champs).

La section record doit donc contenir une ou plusieurs balises <property>. Voici une balise <property> avec la liste des attributs possibles :

  <property 
      name="nom simplifié" 
      fieldname="nom du champ" 
      datatype="" required="true/false" minlength="" maxlength="" regexp="" 
      sequence="nom de la sequence" autoincrement="true/false"
      updatepattern="" insertpattern="" selectpattern=""
      default=""
      comment=""
   />

L'attribut name est le nom de la propriété de l'objet.

L'attribut fieldname est le nom du champ qui correspond. Si name et fieldname sont égaux, on peut omettre fieldname.

Les attributs datatype, required, minlength, maxlength, et regexp sont des contraintes. Cela permet par la suite d'appeler la méthode check() sur un record pour vérifier les valeurs des propriétés (avant son stockage par exemple).

L'attribut default permet d'indiquer une valeur par défaut.

L'attribut datatype indique le type SQL du champs. Voici les types de champs reconnus par jDao, qui sont bien plus nombreux que dans les versions précédentes de jelix :

• varchar, varchar2, nvarchar2, character, character varying, char, nchar, name, longvarchar, string (deprecated),
• int, integer, tinyint, smallint, mediumint, bigint,
• autoincrement, serial, bigserial, bigautoincrement,
• double, double precision, float, real, number, binary_float, binary_double, money,
• numeric, decimal, dec,
• date, time, datetime, timestamp, utimestamp, year, interval
• boolean, bool, bit
• tinytext, text, mediumtext, longtext, long, clob, nclob
• tinyblob, blob, mediumblob, longblob, bfile,
• varbinary, bytea, binary, raw, long raw
• enum, set, xmltype, point, line, lsed, box, path, polygon, circle, cidr, inet, macaddr, bit varyong, arrays, complex types

Les bases de données ne reconnaissent pas tous ces types de champs. Ne vous inquietez pas, indiquez le type que vous voulez, et jDao utilisera le type qui correspond le mieux pour la base de donnée utilisée. Par exemple, si vous indiquez bytea, c'est un type utilisé par postgresql. Si vous utilisez mysql, jDao utilisera en fait le type longblob.

Les valeurs des champs seront convertis dans le type PHP le plus approprié, la plupart du temps, une chaine.

Pour les champs auto incrementés, vous pouvez indiquer le type serial ou autoincrement. Mais dans certain cas, il est préférable d'indiquer le type d'entier (integer, tinyint..) et de mettre un attribut autoincrement à true. Sur certaines bases, on peut associer une séquence à un champ. L'attribut sequence doit alors indiquer son nom.

L'attribut comment permet d'avoir un commentaire sur la propriété. Sa valeur peut être utilisée par la commande createform pour générer les labels des champs de saisie.

Les attributs updatepattern, insertpattern et selectpattern permettent d'indiquer un "motif" à appliquer lors de la mise à jour, l'insertion ou la lecture de la valeur du champ dans la table. Ce motif doit en fait être une expression SQL, contenant éventuellement la chaîne "%s" qui sera remplacée par la valeur ou le nom du champ. Par défaut leurs valeurs vaut "%s". Si on indique une valeur vide, cela correspond à une opération nulle (le champ n'est pas lu, inséré ou mis à jour). Vous pouvez utiliser insertpattern et selectpattern sur des clés primaires, mais pas updatepattern.

Exemple 1 ¶

  <property name="date_update" datatype="datetime" insertpattern="NOW()" updatepattern="NOW()" />

Exemple 2 ¶

  <property name="identite" datatype="string" selectpattern="CONCAT(nom, ' ',prenom)" insertpattern="" updatepattern="" />

Votre classe aura le nom que vous voudrez, avec le suffixe DaoRecord, et stockée dans le répertoire daos/ d'un module, sous le nom <nomclasse>.daorecord.php.

Vous indiquerez alors le sélecteur de cette classe <nommodule>~<nomclasse> dans un attribut extends de la balise <record>.

Notez que votre classe doit étendre la classe jDaoRecordBase.

Exemple, dans le fichier dao :

   <record extends="news~news">
   ...
   </record>

Les enregistrements seront donc de la classe newsDaoRecord située dans le fichier daos/news.daorecord.php du module news.

class newsDaoRecord extends jDaoRecordBase {

   function methodeDeCalcul() {
       $this->champs = $this->champs2 * 1.196;
   }

   function calculateTotal() {
       return $this->amount + $this->vat;
   }
}

Ainsi vous pourrez appeler cette méthode sur n'importe quel enregistrement:

   $maFactory = jDao::get("mymodule~news");
   $liste = $maFactory->findAll();

   foreach ($liste as $row) {
        $total = $row->calculateTotal();
        //...
   }
 

Si votre classe a un namespace et est auto-chargeable, vous pouvez son nom complet dans l'attribut extends de la balise <record>.

Votre classe doit étendre la classe jDaoRecordBase.

Exemple, dans le fichier dao :

   <record extends="\MyCompany\MyDomain\News">
   ...
   </record>

Les enregistrements seront donc de la classe \MyCompany\MyDomain\News située dans un fichier News.php quelque part dans votre module ou ailleurs. Un exemple de son code source :

class \MyCompany\MyDomain\News extends \jDaoRecordBase {

   function methodeDeCalcul() {
       $this->champs = $this->champs2 * 1.196;
   }

   function calculateTotal() {
       return $this->amount + $this->vat;
   }
}

Ainsi vous pourrez appeler cette méthode sur n'importe quel enregistrement:

   $maFactory = jDao::get("mymodule~news");
   $liste = $maFactory->findAll();

   foreach ($liste as $row) {
        $total = $row->calculateTotal();
        //...
   }
 

• le dao à importer est lu en premier : votre Dao possède ainsi toutes ses propriétés, définitions de tables et méthodes.
• les tables, propriétés et methodes de votre dao sont ensuite lues. Celles qui ont le même nom que celles qui viennent d'être importées, écrasent ces dernières. Elles écrasent les tables, propriétés et méthodes du même nom qui viennent d'être importées.
• les classes PHP du DAO résultant sont alors générées.

Notez que l'import n'est pas un héritage au sens objet PHP.

Exemple :

Un bon exemple avec jauthdb : si vous avez besoin de définir votre propre dao, il est noté dans la documentation qu' "il doit avoir au moins les mêmes propriétés et méthodes que le dao jelixusers".

Voici donc par exemple votre dao "mymodule~mycustomuser" :

<dao import="jauthdb~jelixuser">
	<datasources>
		<primarytable name="user" realname="myusertable" primarykey="login" />
	</datasources>
	<record>
		<property name="nationality" fieldname="nationality" datatype="string" maxlength="100" required="true">
	</record>
	<factory>
		<method name="findByNationality" type="select">
			<parameter name="nationality" />
			<conditions>
				<eq property="nationality" expr="$nationality" />
			</conditions>
		</method>
	</factory>
</dao>

Ici, vous aurez donc défini simplement un dao personnalisé pour jauth , tout en respectant les critères de base requis (propriétées login et password, methodes getByLoginPassword, getByLogin, etc...) grace à l'import de jauthdb~jelixuser.