====== Création de Modules Génériques "Jelix" (partie 1/2) ======


//(version de Jelix supportée 1.1.x)//

===== Description =====
 

Un module générique peut revêtir plusieurs aspects, soit une ''simple'' classe métier, soit une forme plus étendue avec une zone par exemple.
Ceci permet d'intégrer des modules au sein de n'importe quelle autre application Jelix.

Pour illustrer ces 2 volets, je prendrai 2 exemples :

  - [[http://bitbucket.org/foxmask/jblog/src/tip/jblog/modules/jtags/|le module jTags de l'application ShareCode]] permet de Tagger billets, photos, films, etc...
  - [[https://bitbucket.org/foxmask/havefnubb/src/tip/havefnubb/modules/hfnurates/|le module HfnuRates de l'application HaveFnuBB]] 

  * Le premier cas permet de stocker les tags lors de la création d'une discussion.
  * Le second cas permet de stocker une "note" d'appréciation d'une discussion (après sa création, bien évidement).

===== Introduction =====
 

  * j'appelle module "générique" le module offrant un service ;
  * j'appelle module "utilisateur" le module exploitant ledit service.

===== PREMIER VOLET : jTags =====


==== INGREDIENTS ====

  - un form
  - un template
  - un contrôleur
  - une classe métier 
  - une zone

Je possède un module de forum listant des pages de discussion et j'ai envi de permettre aux membres de tagger celles-ci.

Disposant déjà d'un "[[http://jelix.org/articles/fr/manuel-1.1/jforms|form]]" Jelix pour gérer les données de ma discussion (posts.form.xml), j'ajoute à ce dernier, un noeud "textarea" nommé "tag", comme suit :

==== FORM ====

<code xml>
<form xmlns="http://jelix.org/ns/forms/1.1">
[...]
<input ref="subject" type="string" required="true" size="80">
	<label locale="havefnubb~post.form.subject"/>
</input>
<textarea ref="message" required="true"  rows="10" cols="80" >
	<label locale="havefnubb~post.form.message"/>
</textarea>
<textarea ref="tags" rows="2" cols="60">
	<label locale="havefnubb~post.form.choose.your.tags"/>
</textarea> 
[...]
</form>
</code>

Ainsi paré, à présent mon module discussion dispose d'un textarea "tags" en plus du titre et du contenu.

**TIPS** Le contenu de la propriété "locale" permet d'internationaliser les libellés du formulaire.

==== LE TEMPLATE edit ====


Voyons maintenant comment est présenté le template **edit** à l'utilisateur :
<code>
{form $form, 'havefnubb~posts:save', array('id_post'=>$id_post)}
<fieldset>
<p>{ctrl_label 'subject'} </p>
<p>{ctrl_control 'subject'} </p>
<p>{ctrl_label 'tags'} </p>
<p>{ctrl_control 'tags'} </p>    
<p>{ctrl_label 'message'} </p>
<p>{ctrl_control 'message'} </p>
</fieldset>
<div>{formsubmit 'validate'} {formreset 'cancel'}</div>
{/form}
</code>

  * $form est l'instance de mon formulaire Jelix, suivent, l'action à effectuer (havefnubb~posts:save) et les paramètres à passer quand les données sont soumises. 
  * les {ctrl_control xxx} affichent les champs définis dans posts.form.xml


==== LE CONTROLEUR ====


A présent le contrôleur ci-dessous nous montre comment est instancié le formulaire @@F@$form@@ dans la méthode **edit**, 
et ce qui se produit quand le formulaire est enregistré (methode **save**)

<code php>
class postsCtrl extends jController {
    //let's init the form 
   function edit() {    
        $id_post  = $this->intParam('id_post');
        $srvTags = jClasses::getService("jtags~tags");
	$tags = implode(',',$srvTags->getTagsBySubject('forumscope', $id_post));

        // new instance of jForms
	$form = jForms::create('havefnubb~posts',$id_post);
        // initiate the data from the dao "posts"
	$form->initFromDao("havefnubb~posts");
        // set the tags data to the form
	$form->setData('tags', $tags);	
        $rep = $this->getResponse('html');	
        $tpl = new jTpl();
        $tpl->assign('id_post', $id_post);
        $tpl->assign('form', $form);        
        [...]
        // let's display the form
	return $rep;
	}
    //let's save the datas
    function save() {
        $id_post  = $this->intParam('id_post');
        //get the instance of a previous jForms::create()
        $form = jForms::fill('havefnubb~posts',$id_post);
        // get the posted data
        $tags = explode(",", $form->getData("tags"));
        //call the class jTags and give the data to store
        jClasses::getService("jtags~tags")->saveTagsBySubject($tags, 'forumscope', $id_post);        
        // destroy the instance
        jForms::destroy('havefnubb~posts', $id_post);
        $rep = $this->getResponse('html');
        [...]
        $rep->action ='havefnubb~posts:view';
        // let's go to the view page
        return $rep;
	}	
    function view () {
        [...]
    }
}
</code>

==== LA CLASSE ====

la classe métier de jTags s'occupe de gérer les données soumises via les 2 méthodes edit/save du contrôleur ci dessus.
<code php>
class tags {    
    function getTagsBySubject($scope, $id) {
        //read the table and retreive the datas
        [...]
    }
    function saveTagsBySubject($tags, $scope, $id) {
        //save the datas submitted 
        [...]
    }    
}
</code>

Pour que la "magie" opère nous stockons donc dans la table du module "générique", 
les variables @@P@$scope@@ et @@P@$id@@ qui permettent de relier les "Tags" à la "Discussion".

==== ZONE ====


Pour parachever le tout nous disposons d'une zone listant la totalité du nuage de tags, utilisable depuis le template de son choix comme suit :

<code php>
{zone "jtags~tagscloud",array('destination'=>'havefnubb~default:cloud')}
</code>
ici ''destination'' permet lors du clique sur un tag, d'indiquer à jelix, vers quelle action envoyer l'utilisateur

===== Conclusion =====



Grâce à la souplesse du module jTags, il suffit de 2 points d'attache entre le module Forum et le module jTags pour permettre au premier d'exploiter le second

ici les points d'attache entre le module "utilisateur" et le module "générique" sont : 
  * le textarea qui fait apparaitre le champ tags dans le formulaire
  * la classe tags appelée depuis les méthodes du contrôleur

Suite : [[fr:tutoriels:modules:generic2|Création de module génériques (2/2)]]