Table of Contents

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

Description

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…

Introduction

PREMIER VOLET : jTags

INGREDIENTS

  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

<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.

LE TEMPLATE edit

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}

LE CONTROLEUR

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

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”.

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 :

{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

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 :

Suite : Création de module génériques (2/2)