Creation of Generic "Jelix" Modules (part 1/2) ¶

A generic module

A generic module can take various forms, a simplebusiness class, or a larger one with a zone for example. This allows the integration of modules in any application Jelix.

To illustrate these two aspects, I will take two examples:

1. the module jTags of the application ShareCode permits to tag various things : posts, photos, movies, etc…
2. the module HfnuRates of the application HaveFnuBB

• The first case permits to save the tags when creating a topic
• the second case permits to save a “note” of appreciation of a discussion (after its creation, of course)

• j'appelle module “générique” le module offrant un service ;
• j'appelle module “utilisateur” le module exploitant ledit service.

1. un form
2. un template
3. un contrôleur
4. une classe métier
5. 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 “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 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>

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.

Voyons maintenant comment est présenté le template edit à l'utilisateur :

{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}

• $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

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

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 () {
        [...]
    }
}

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.

class tags {    
    function getTagsBySubject($scope, $id) {
        //read the table and retreive the datas
        [...]
    }
    function saveTagsBySubject($tags, $scope, $id) {
        //save the datas submitted 
        [...]
    }    
}

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

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 :

{zone "jtags~tagscloud",array('destination'=>'havefnubb~default:cloud')}

ici destination permet lors du clique sur un tag, d'indiquer à jelix, vers quelle action envoyer l'utilisateur

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 : Création de module génériques (2/2)