Tutorial

Introduction

Dans ce petit tutoriel, nous allons créer une application toute simple qui nous permettra de voir un maximum de concept de ce framework.
Pour cela nous allons utiliser le builder, qui va nous générer une application vierge, puis nous paramétrons sa base de donnée...
Mais d'abord une petite introduction au mkframework et son fonctionnement: lorsque vous appelez une page, le dispatcher en fonction de l'url va
définir quel module vous appelez, et quel action (exple: module article, action lister ou module article, action editer)

Prenons pour exemple article::list
- Avant d'executer l'action il execute la methode before() (si elle existe)
- Ensuite il execute la methode portant le nom de l'action (nomdelaction précédée par un underscode exple: _list)
- Apres avoir executer cette methode, il executera (si elle existe) la methode after() du module

Dans cette méthode, on va faire nos accès aux données, faire nos différents traitements, creer une vue, lui assigner les variables nécessaires
puis ajouter cette(ces) vue(s) au layout general
pour finalement afficher le layout general (methode show)

On peut entre temps, ajouter ces vues a different emplacements (main,menu...), mais nous verrons ca plus tard.

On verra egalement dans ce tutorial comment agencer differentes briques (module): article et ses commentaires.

L'application qui va être développée

L'application choisi sera un modeste gestionnaire de contenu permettant de créer des articles, de les modifier et pourquoi pas laisser la possibilité d'être commenté
Le fameux blog en 15 minutes dont d'autres framework ont déjà fait la promo.

Installation

Telecharger le mkframework en cliquant sur le lien situé sur le site. Vous recuperez une archive au format zip.
Décompressez la dans le repertoire web de votre serveur apache, (repertoire www/ ou htdocs/ selon votre environnement)
Dans ce tutoriel, on part du principe que vous avez installé le framework à la racine de votre repertoire web, il est donc accessible via l'adresse http://localhost/mkframework_v4_XX_XX/

Pour information le zip comprend le builder et la librairie du framework
Toutes les applications generées lient la librairie du builder (qui peut etre copié, deplacé... en n'oubliant pas de parametrer sa nouvelle adresse)

Creation des tables en base de donnée

CREATE TABLE `article` (
`id` int(11) NOT NULL auto_increment,
`titre` varchar(50) NOT NULL,
`resume` text NOT NULL,
`auteur_id` int(11) NOT NULL,
PRIMARY KEY (`id`)
);

CREATE TABLE `auteur` (
`id` int(11) NOT NULL auto_increment,
`nom` varchar(30) NOT NULL,
`prenom` varchar(30) NOT NULL,
PRIMARY KEY (`id`)
);

Première étape la création d'une nouvelle application

Ouvrez votre navigateur à l'adresse http://localhost/mkframework_v4_XX_XX/
Cliquez dans le menu sur "créer un site"

Entrez le nom de l'application à créer, ici : blog

Cliquez sur le bouton "créer"
L'application mkbuilder va générer une nouvelle application vierge dans le repertoire mkframework_v4_XX_XX/data/genere/blog

Paramétrer la connexion à la base de donnée

Lors de la création d'une nouvelle application, le buider créer une arborescence complète comprenant des librairies, des fichiers css, de config...
On peut depuis le builder éditer le fichier de configuration conf/connexion.ini.php de votre application. Ce fichier permet de gérer plusieurs configuration de connexion
aussi bien plusieurs paramètres de connexion (user,base différente) que des bases différentes: mysql/postgresql...
Vous pouvez ainsi stocker vos articles sur mysql et vos user sur postgresql...
Pour paramétrer vos connexions le plus simplement du monde, editer le fichier conf/connexion.ini.php (situé dans data/genere/nomduprojet)

Générer la couche modèle

Le framework étant basé sur une architecture MVC, il nous faut créer la couche M: Modèle.
Pour cela rien de plus simple, cliquez sur "générer la couche modèle", cliquez sur le lien de la configuration à utiliser.
Vous verrez s'afficher la liste des tables trouvées suivi d'un menu deroulant permettant de designer la clé primaire.

Enrichissons un peu cette couche modèle

La couche modèle généré automatiquement est brute (elle ne comprend pas ici ni les jointures...)
Pour notre exemple on souhaiterai avoir un menu deroulant pour selectionner l'auteur lie a l'article
Pour cela on peut ajouter dans la classe model d'auteur une methode getSelect() qui retournera un tableau de type id/valeur

Dans model/model_auteur.php

CODE



 class model_auteur extends abstract_model{
(...)

public function getSelect(){
$tMany=$this->findMany('SELECT * FROM '.$this->sTable);
$tSelect=array();
foreach($tMany as $oAuteur){
$tSelect[ $oAuteur->id ]=$oAuteur->nom;
}
return $tSelect;
}
}

Nous avons pour ce projet une jointure entre les commentaires et les articles.
Il faudrait donc avoir a partir d'un article sa liste de comentaire.
Pour cela on va ajouter deux methodes (pour faire propre)
Une premiere methode dans commentaire, permettant de lister des commentaire par article
Dans model/model_commentaire.php

CODE



 class model_commentaire extends abstract_model{
(...)

public function findByArticle($article_id){
return $this->findMany('SELECT * FROM '.$this->sTable.' where article_id=?',$article_id);
}
}

Une seconde methode sera créée dans la classe row d'article permettant de recuperer ses commentaires
Ceci en faisant simplement appel a la methode precedement ajoutée
Dans model/row_article.php

CODE



 class row_article extends abstract_row{
(...)

public function findCommentaires(){
return model_commentaire::getInstance()->findByArticle($this->id);
}
}

Génération du CRUD qu'est-ce que c'est ?

CRUD Create Read Update Delete, les quatre actions d'une base de donnée.
Et bien le mkframework vous permet de générer facilement le crud pour chaque table.
Pour cela cliquez sur "générer le CRUD", cliquez sur la configuration a utiliser
La une liste des tables disponible dans notre base va s'afficher.

Cliquez sur "article"

Vous allez voir apparaître la liste des champs de cette table ainsi suivi d'un de son type (text,textarea,date,select).
Vous pouvez ici si c'est le cas configurer des menus deroulants s'appuyant sur la methode getSelect() d'une table etrangère (precedement créé)
Par exemple dans notre cas, on voudrais bien choisir un auteur dans un menu deroulant plutot que de saisir son id :)
Naturellement on selectionnera dans le menu deroulant en face d'auteur_id "select sur table "Auteur"" qui utilisera la methode précedement ajoutée. (model_auteur::getSelect())
Cliquez sur "générer le CRUD"
Et voila le crud de votre table article est généré
Recommencer pour commentaire, et auteur

Visionnez l'application en cours de route

Rendez vous à l'adresse du mkbuilder, et cliquez dans le menu sur "lister les sites" vous voyez ainsi une liste des application que vous avez généré

Cliquez sur blog
Vous voila sur votre site généré. vous pouvez remarquer en bas a gauche dans votre menu "article", cliquez dessus pour voir le CRUD généré.

Les briques générées, il faut faire l'intégration

On veut lister les articles, et en cliquant sur l'un d'eux voir un article en entier, + voir la liste des commentaires associé
+ un formulaire pour en ajouter.

Toutes briques nous les avons généré lors de la génération du CRUD de chaque table
La liste des articles, nous l'avons
La liste des commentaires, nous l'avons
Le formulaire d'ajout de commentaire, nous l'avons, il faut le modifier pour forcer l'id de l'article

Pour ajouter ces differentes briques a notre template, on va utiliser la flexibilité de ce framework
Si vous regardez les classes modules générées, vous noterez que pour chaque action on fait appel a une methode qui nous retourne son objet vue (oTpl)
C'est pour permettre d'optimiser la reutilisabilité dont on va faire usage simplement ici
On va d'ailleurs ajouter au module commentaire la possibilité de lister les commentaires par article

On copie la methode getList()

CODE



 public function getList(){
$oModelCommentaire=new model_commentaire;
$tCommentaire=$oModelCommentaire->findAll();

$oTpl=new _tpl('commentaire::list');
$oTpl->tCommentaire=$tCommentaire;
$oTpl->tColumn=$oModelCommentaire->getListColumn();

return $oTpl;
}

En modifiant deux choses: un l'ajout d'un parametre article_id a cette methode, deux l'utilisation d'une autre methode findByArticle (precedement ajoutée)

CODE



 public function getListByArticle($article_id){
$oModelCommentaire=new model_commentaire;
$tCommentaire=$oModelCommentaire->findByArticle($article_id);

$oTpl=new _tpl('commentaire::list');
$oTpl->tCommentaire=$tCommentaire;
$oTpl->tColumn=$oModelCommentaire->getListColumn();

return $oTpl;
}

Pour les commentaires, il faut que forcer les commentaires avec l'article en lecture, mais il faut aussi que lors de l'enregistrement on revienne sur la page de lecture de l'article.

On commence par copier la methode getNew()

CODE



 public function getNew(){
$oModelCommentaire=new model_examplemodule;
$oCommentaire=new row_commentaire;

$oTpl=new _tpl('commentaire::new');
$oTpl->oCommentaire=$oCommentaire;
$oTpl->tColumn=$oModelCommentaire->getListColumn();
$oTpl->tId=$oModelCommentaire->getIdTab();

return $oTpl;
}

En modifiant deux choses: un l'ajout d'un parametre article_id, deux l'assignation de l'article_id a la vue newByArticle

CODE



 public function getNewByArticle($article_id){
$oModelCommentaire=new model_examplemodule;
$oCommentaire=new row_commentaire;

$oTpl=new _tpl('commentaire::newByArticle');
$oTpl->oCommentaire=$oCommentaire;
$oTpl->tColumn=$oModelCommentaire->getListColumn();
$oTpl->tId=$oModelCommentaire->getIdTab();
$oTpl->article_id=$article_id;

return $oTpl;
}

On copie egalement la vue module/commentaire/tpl/new.php

CODE



 (...)
<form action="<?php echo $this->getLink('examplemodule::save',array(
)
)?>" method="POST">
(...)

En modifiant juste l'action appellée saveByArticle au lieu de save

CODE



 (...)
<form action="<?php echo $this->getLink('examplemodule::saveByArticle',array(
'article_id'=>$this->article_id
)
)?>" method="POST">
(...)

Il faut donc creer cette methode ou on forcera la redirection vers la page de lecture de l'article article::showensemble

CODE



 public function saveByArticle(){
$oModelCommentaire=new model_commentaire;

$oCommentaire=new row_commentaire;
$oCommentaire->auteur_id=_root::getParam('auteur_id');

foreach($oExamplemoduleModel->getListColumn() as $sColumn){
if( _root::getParam($sColumn,null) ==null ) continue;
if( in_array($sColumn,$oExamplemoduleModel->getIdTab())) continue;
$oExamplemodule->$sColumn=_root::getParam($sColumn,null) ;
}

$oExamplemodule->save();

_root::redirect('artiche::showensemble',array('id'=> $oCommentaire->auteur_id ));
}

On va inclure la liste des article, l'affichage de celui-ci et la liste des commentaires associés.
Pour cela on a deux facons differentes de proceder
1. on creer un layout specialement pour l'occasion, en y ajoutant des <?php echo $this->load('nomDeLaZone') ?>
2. on assigne les vues retournées (par commentaire/list , article/list et article/show) a une vue ou on les affichera en appelant leur methode show()

Pour la solution 2
Pour cela dans le fichier module/article/main.php, on va indiquer

CODE



 //dans la fonction function _showensemble(){

$id=_root::getParam('id');

$oTpl=new _tpl('article::showensemble');
$oTpl->oTplListArticle=module_article::getInstance()->getList();
$oTpl->oTplShowArticle=module_article::getInstance()->getShow($id);
$oTpl->oTplListCommentaire=module_commentaire::getInstance()->getListByArticle($id);
$oTpl->oTplNewCommentaire=module_commentaire::getInstance()->getNewByArticle($id);

$this->oLayout->add('main',$oTpl);

Dans la vue article/tpl/showensemble.php

CODE



 ?>
<!--ICI le contenu html d'affichage de notre article-->
<?php echo $this->oTplListArticle->show()?>

<!--ICI le detail de l'article-->
<?php echo $this->oTplShowArticle->show()?>

<!--ICI la liste les commentaires-->
<?php echo $this->oTplListCommentaire->show()?>

<!--ICI le formulaire d'ajout de commentaires-->
<?php echo $this->oTplNewCommentaire->show()?>

Un peu de mise en forme

Après un peu de mise en forme: modification du css, ainsi que des vues module/articles/tpl/show.php, module/commentaires/tpl/list.php
On obtient ceci
On peut également modifier le module menu assez facilement en éditant module/menu/main.php

That's all

Voila on a fini c'était pas trop dur grâce au mkbuilder.
De plus la syntaxe générale est assez pratique et facilement assimilable.

Ce qu'on a appris dans ce tutorial

On a appris a utiliser le mkbuilder:
- générer une application vierge,
- administrer sa connexion,
- générer la couche modèle,
- générer le CRUD d'une table
On a appris a utiliser le framework
- comment charger un module a un emplacement
- comment ajouter des méthodes dans la couche modèle pour simuler d'autres requêtes