ZnetDK | Tutoriel

Image n°1

Je vous propose de réaliser votre premier développement avec ZnetDK en déroulant le Tutoriel qui suit.

Il va vous montrer comment ajouter à l'application de démarrage livrée avec ZnetDK, l'enregistrement en base de données d'une liste de fournisseurs.

Nous allons suivre pour cela les 5 grandes étapes suivantes :

Menu Mes fournisseurs : ajouter une nouvelle entrée de menu Mes fournisseurs,
Table SQL fournisseurs : créer une table SQL destinée à contenir les données fournisseurs,
Classe FournisseurDAO : définir une classe de type DAO pour accéder à la table SQL des fournisseurs,
Classe contrôleur FournisseurCtrl : implémenter une classe de type contrôleur pour alimenter la vue en données et pour traiter côté serveur les actions de l'utilisateur.
Vue mesfournisseurs.php : créer la vue HTML5 d'affichage de la liste des fournisseurs complétée des boutons d'action pour l'ajout, modification et suppression d'un fournisseur.

Ce développement une fois terminé ressemblera à la photo d'écran de l'image n°1.

Le code source des fichiers créés ou modifiés dans ce tutoriel est disponible à la rubrique Téléchargements.

Menu Mes fournisseurs

Image n°2

L'ajout d'un nouveau menu consiste simplement à compléter la classe Menu dont la définition se trouve dans le script menu.php situé sous /applications/default/app/.

A la dernière ligne de la méthode initAppMenuItems(), faites un appel à la méthode statique \MenuManager::addMenuItem() pour ajouter en dernière position du menu, la nouvelle entrée nommée Mes fournisseurs, comme montré ci-dessous à la ligne 14 :


namespace app;
class Menu implements \iMenu {

  static public function initAppMenuItems() {
    \MenuManager::addMenuItem(null,'check_connection',LC_MENU_HOME,'ui-icon-home');
    \MenuManager::addMenuItem(null,'_themes',LC_MENU_THEMES,'ui-icon-lightbulb');
    \MenuManager::addMenuItem('_themes','try_themes',LC_MENU_THEMES,'ui-icon-image');
    \MenuManager::addMenuItem('_themes','check_widgets',LC_MENU_EXAMPLE,'ui-icon-star');
    \MenuManager::addMenuItem(null,'_authorization',LC_MENU_AUTHORIZATION,'ui-icon-key');
    \MenuManager::addMenuItem('_authorization','users',LC_MENU_AUTHORIZ_USERS,'ui-icon-person');
    \MenuManager::addMenuItem('_authorization','profiles',LC_MENU_AUTHORIZ_PROFILES,'ui-icon-link');
	
    /* Nouvel élément "Mes fournisseurs" ajouté au menu de l'application */
    \MenuManager::addMenuItem(null,'mesfournisseurs','Mes fournisseurs');
  }

}

A présent, si vous accédez à votre application, vous devriez disposer d'un nouvel onglet Mes fournisseurs comme illustré sur l'image n°2.

Vous noterez au passage que l'intitulé de menu Mes fournisseurs est directement renseigné dans la méthode addMenuItem() contrairement aux autres entrées de menu de la classe dont l'intitulé est précisé à travers une constante nommée PHP (par exemple LC_MENU_HOME).
L'application de démarrage ZnetDK est en effet traduite en 3 langues et l'utilisation de constantes nommées est ici le moyen de disposer du menu dans les différentes langues traduites pour l'application (rendez-vous à la rubrique Gestion multilingue pour en savoir plus).

Table SQL fournisseurs

Créez maintenant dans la base de données MySQL que vous avez configurée à l'installation de ZnetDK, la table fournisseurs en exécutant la commande SQL ci-dessous :

CREATE TABLE fournisseurs (
  id int(11) NOT NULL AUTO_INCREMENT,
  nom varchar(50) COLLATE utf8_unicode_ci NOT NULL,
  adresse varchar(100) COLLATE utf8_unicode_ci DEFAULT NULL,
  code_postal varchar(5) COLLATE utf8_unicode_ci DEFAULT NULL,
  ville varchar(50) COLLATE utf8_unicode_ci DEFAULT NULL,
  PRIMARY KEY (id),
  UNIQUE KEY fournisseurs_nom_uk (nom)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;

La persistence des données fournisseurs sera assurée par cette nouvelle table. Les opérations de consultation , recherche et mise à jour effectuées sur la table fournisseurs seront sous le contrôle exclusif d'un objet DAO dont la classe FournisseurDAO est définie au paragraphe qui suit.

Classe FournisseurDAO

Pour créer la classe FournisseurDAO, ajoutez un nouveau script PHP nommé fournisseurdao.php dans le répertoire /applications/default/app/model/ et insérez le code source suivant :

<?php
namespace app\model;
class FournisseurDAO extends \DAO
{
	protected function initDaoProperties() {
		$this->table = "fournisseurs";
	}
}

La dérivation de la classe abstraite \DAO en FournisseurDAO et l'initialisation de la propriété table dans la méthode surchargée initDaoProperties() sont suffisantes pour accéder aux données des fournisseurs, comme nous le verrons en détail au paragraphe suivant consacré à l'implémentation du contrôleur FournisseurCtrl.

Classe contrôleur FournisseurCtrl

La classe FournisseurCtrl va prendre en charge les demandes d'ajout, modification et suppression d'un fournisseur et l'alimentation en données de la vue fournisseur.php pour affichage de la liste des fournisseurs dans le composant graphique zdkdatatable.

Elle dérive de la classe abstraite \AppController et ses méthodes d'action sont appelées par le contrôleur de façade lorsqu'une requête HTTP est envoyée à la page index.php avec les paramètres POST control=fournisseurctrl et action=<nom_de_l_action> (où <nom_de_l_action> prend la valeur lister, enregistrer ou supprimer).

Chaque méthode du contrôleur correspondant à une action doit avoir une portée protected et respecter la convention de nommage action_<nom_de_l_action>().

Ajoutez à présent un nouveau script PHP nommé fournisseurctrl.php dans le répertoire /applications/default/app/controller et insérez le code suivant :

<?php
namespace app\controller;
class FournisseurCtrl extends \AppController
{
    static protected function action_lister() {
		/* A COMPLETER */
    }
    static protected function action_enregistrer() {
		/* A COMPLETER */
    }
    static protected function action_supprimer() {
		/* A COMPLETER */
    }
}

Le code PHP de la classe FournisseurCtrl tel qu'il est présenté ci-dessus ne contient pas encore la logique métier du contrôleur. Il se limite pour l'instant à établir le lien entre chaque action adressée au contrôleur et la méthode d'action à exécuter en correspondance.
Intéressons-nous désormais à l'implémentation de chacune de ces méthodes d'action.

Méthode action_lister()

Cette méthode fournit la liste de tous les fournisseurs qui seront affichés dans un tableau HTML dans la vue fournisseur.php (vue présentée au paragraphe suivant) en réponse à l'action lister envoyée au contrôleur depuis le navigateur internet.
Cette liste est constituée par l'interrogation de la méthode getResult() de la classe \app\model\FournisseurDAO développée au chapitre précédent.
Les données fournisseurs sont retournées par la méthode à travers un objet de la classe ZnetDK \Response.
Le contrôleur de façade ZnetDK prend enfin le relais pour générer la réponse HTTP sous la forme d'un tableau d'objets encodé au format texte JSON, en précisant dans l'entête le type de contenu qui convient (Content-type: application/json).

static protected function action_lister() {
	$fournisseurDAO = new \app\model\FournisseurDAO();
	$fournisseurs = array();
	while($row = $fournisseurDAO->getResult()) {
		$fournisseurs[] = $row;
	}
	/* Réponse retournée au contrôleur de façade */
	$response = new \Response();
	$response->rows = $fournisseurs;
	$response->success = true;
	return $response;
}

Méthode action_enregistrer()

La méthode action_enregistrer() est déclenchée en réponse à l'action enregistrer pour insérer en base de données un nouveau fournisseur ou mettre à jour les données d'un fournisseur existant.

Les données du fournisseur à enregistrer sont transmises au contrôleur par le biais de paramètres POST dont les valeurs sont lues par l'intermédiaire d'un objet de la classe ZnetDK \Request.
Ces données sont ensuite transmises à la méthode store() du DAO de type \app\model\FournisseurDAO pour enregistrement en base de données du fournisseur.
Le DAO détermine s'il doit créer un nouveau fournisseur (ordre SQL INSERT) ou seulement mettre à jour les données d'un fournisseur existant (ordre SQL UPDATE), selon que l'identifiant du fournisseur (paramètre POST id) est renseigné ou non.

Pour finir, une réponse sous forme d'objet \Response est retournée au contrôleur de façade pour indiquer à l'utilisateur si l'enregistrement du fournisseur a réussi (appel de la méthode setSuccessMessage()) ou non (appel de la méthode setFailedMessage()).

static protected function action_enregistrer() {
	/* Lecture des données de la requête HTTP */
	$request = new \Request();
	$row = $request->getValuesAsMap('id','nom','adresse','code_postal','ville');
	
	/* Enregistrement des données en Base de données */
	$fournisseurDAO = new \app\model\FournisseurDAO();
	$result = $fournisseurDAO->store($row);
	
	/* Réponse retournée au contrôleur de façade */
	$response = new \Response();
	if ($result) {
	  $response->setSuccessMessage('Enregistrement',
		'Enregistrement du fournisseur réussi.');
	} else {
	  $response->setFailedMessage('Enregistrement',
		"Echec d'enregistrement du fournisseur.");
	}
	return $response;
}

Méthode action_supprimer()

La suppression d'un fournisseur en réponse à l'action supprimer est effectuée à partir de l'identifiant du fournisseur transmis via le paramètre POST id.
Cet identifant est transmis en paramètre de la méthode remove() du DAO des fournisseurs pour supprimer le fournisseur en base de données.
Une réponse est également retournée par la méthode pour confirmer à l'utilisateur la suppression effective du fournisseur.

static protected function action_supprimer() {
	/* Lecture des données de la requête HTTP */
	$request = new \Request();
	$rowID = $request->id;
	
	/* Suppression du fournisseur en Base de données */
	$fournisseurDAO = new \app\model\FournisseurDAO();
	$result = $fournisseurDAO->remove($rowID);
	
	/* Réponse retournée au contrôleur de façade */
	$response = new \Response();
	if ($result) {
	  $response->setSuccessMessage('Suppression',
		'Suppression du fournisseur réussie.');
	} else {
	  $response->setFailedMessage('Suppression',
		'Echec de suppression du fournisseur.');
	}
	return $response;
}

Vue mesfournisseurs.php

L'étape actuelle de ce tutoriel consiste à développer la vue de l'application, contenant la définition HTML :

des 3 boutons d'ajout, modification et suppression d'un fournisseur (balises <button/>),
du tableau des fournisseurs (balise <div id="table_fournisseurs"/>)
et de la boîte de dialogue contenant le formulaire de saisie d'un fournisseur (balises <div id="dlg_fournisseur"/>).

Pour commencer, créez le script PHP de la vue dans le répertoire /applications/default/app/view/ que vous nommerez mesfournisseurs.php et dans lequel vous ajouterez le code HTML suivant.

<!-- Boutons d'action -->
<div class="zdk-action-bar" data-zdk-dialog="dlg_fournisseur" 
							data-zdk-datatable="table_fournisseurs">
    <button class="zdk-bt-add" title="Nouveau fournisseur">Ajouter</button>
    <button class="zdk-bt-edit" title="Modification du fournisseur">Modifier</button>
    <button class="zdk-bt-remove" title="Suppression du fournisseur" 
			data-zdk-action="fournisseurctrl:supprimer">Supprimer</button>
</div>
<!-- Tableau des fournisseurs -->
<div id="table_fournisseurs" class="zdk-datatable" title="Fournisseurs"
        data-zdk-action="fournisseurctrl:lister"
		data-zdk-columns='[{"field":"id", "headerText": "Numéro"},
                {"field":"nom", "headerText": "Nom"},
                {"field":"adresse", "headerText": "Adresse"},
                {"field":"code_postal", "headerText": "Code postal"},
                {"field":"ville", "headerText": "Ville"}]'>
</div>
<!-- Formulaire dans boîte de dialogue -->
<div id="dlg_fournisseur" class="zdk-modal" title="Fournisseur">
    <form class="zdk-form"
		data-zdk-action="fournisseurctrl:enregistrer"
		data-zdk-datatable="table_fournisseurs">
		<label>Numéro : </label>
		<input name="id" disabled type="text">
		<label>Nom : </label>
		<input name="nom" maxlength="50" required type="text">
		<label>Adresse : </label>
		<textarea name="adresse" rows="3" maxlength="100"></textarea>
		<label>Code postal : </label>
		<input name="code_postal" maxlength="5" required type="text">
		<label>Ville : </label>
		<input name="ville" maxlength="50" required type="text">
        <button class="zdk-bt-save zdk-close-dialog" type="submit">Enregistrer</button>
        <button class="zdk-bt-cancel zdk-close-dialog" type="button">Annuler</button>
    </form>
</div>

Attention, afin que ZnetDK puisse retrouver la vue à appeler pour l'élement de menu Mes fournisseurs, le nom de ce script doit impérativement se nommer selon le format <menuItemID>.php où <menuItemID> correspond à l'identifiant mesfournisseurs du menu ajouté à la classe Menu en début de tutoriel.

Ces éléments HTML que vous venez d'ajouter à la vue servent de points d'ancrage aux composants graphiques PrimeUI.
Nul besoin d'instancier un par un les composants PrimeUI, ZnetDK s'en charge pour vous après le chargement réussi de la vue.

Etudions à présent d'un peu plus près le code HTML de la vue et le procédé par lequel ZnetDK crée de manière automatique les composants graphiques PrimeUI.

Les boutons d'action

<!-- Boutons d'action -->
<div class="zdk-action-bar" data-zdk-dialog="dlg_fournisseur"
					        data-zdk-datatable="table_fournisseurs">
    <button class="zdk-bt-add" title="Nouveau fournisseur">Ajouter</button>
    <button class="zdk-bt-edit" title="Modification du fournisseur">Modifier</button>
    <button class="zdk-bt-remove" title="Suppression du fournisseur" 
			data-zdk-action="fournisseurctrl:supprimer">Supprimer</button>
</div>

Etant donné que la vue mesfournisseurs.html comprend à la ligne 2 une DIV de classe zdk-action-bar, ZnetDK instancie automatiquement le composant Javascript zdkactionbar chargé :

d'une part de créer les boutons PrimeUI (voir le widget puibutton) à partir de leur définition HTML (balises <button/>) qui est faite à l'intérieur de la DIV,
d'autre part de réagir aux événements de clic de bouton pour exécuter l'action associée qui convient.

Le composant Javascript zdkactionbar s'appuie à la fois sur la définition de classes de styles (préfixées zdk-) et d'attributs HTML5 (préfixés data-zdk) pour interagir avec les autres composants Javascript de la vue et les contrôleurs PHP développés côté serveur web.

L'attribut data-zdk-dialog renseigné à la ligne 2 pour la DIV, contient l'identifiant HTML dlg_fournisseur de la boîte de dialogue à ouvrir au clic des boutons d'ajout et de modification d'un fournisseur.
L'attribut data-zdk-datatable quant à lui, contient l'identifiant HTML table_fournisseurs du tableau des fournisseurs à interroger pour connaître la ligne sélectionnée au clic des boutons de modification et de suppression d'un fournisseur.

Image n°3

Les classes de style zdk-bt-add, zdk-bt-edit et zdk-bt-remove définies pour les boutons HTML <button/>, permettent d'identifier la fonction de chacun d'eux et de déterminer l'icone appropriée à leur action, tel que cela est montré sur l'image n°3.

Enfin, l'attribut data-zdk-action renseigné à la ligne 6 pour le bouton de suppression d'un fournisseur, indique le nom du contrôleur PHP (contrôleur fournisseurctrl) et le nom de l'action dans le contrôleur (action supprimer), à invoquer au clic du bouton (voir la méthodeaction_supprimer développée au chapitre précédent).

Le tableau des fournisseurs

<!-- Tableau des fournisseurs -->
<div id="table_fournisseurs" class="zdk-datatable" title="Fournisseurs"
        data-zdk-action="fournisseurctrl:lister"
		data-zdk-columns='[{"field":"id", "headerText": "Numéro"},
                {"field":"nom", "headerText": "Nom"},
                {"field":"adresse", "headerText": "Adresse"},
                {"field":"code_postal", "headerText": "Code postal"},
                {"field":"ville", "headerText": "Ville"}]'>
</div>

Selon le même principe que les boutons d'action, ZnetDK détecte à la ligne 10 de la vue, la présence d'une DIV de classe zdk-datatable et instancie alors automatiquement et à votre place, le composant graphique zdkdatatable.

Image n°4

L'attribut data-zdk-action de la ligne 11 connecte le composant zdkdatatable à l'action lister du contrôleur fournisseurctrl (voir la méthode action_lister développée au chapitre précédent).

La définition détaillée des colonnes du tableau des fournisseurs est quant à elle effectuée par l'intermédiaire de l'attribut data-zdk-columns aux lignes 12 à 16, selon la notation JSON (voir image n°4).

Le formulaire de saisie

<!-- Formulaire dans boîte de dialogue -->
<div id="dlg_fournisseur" class="zdk-modal" title="Fournisseur">
    <form class="zdk-form"
		data-zdk-action="fournisseurctrl:enregistrer"
		data-zdk-datatable="table_fournisseurs">
		<label>Numéro : </label>
		<input name="id" disabled type="text">
		<label>Nom : </label>
		<input name="nom" maxlength="50" required type="text">
		<label>Adresse : </label>
		<textarea name="adresse" rows="3" maxlength="100"></textarea>
		<label>Code postal : </label>
		<input name="code_postal" maxlength="5" required type="text">
		<label>Ville : </label>
		<input name="ville" maxlength="50" required type="text">
        <button class="zdk-bt-save zdk-close-dialog" type="submit">Enregistrer</button>
        <button class="zdk-bt-cancel zdk-close-dialog" type="button">Annuler</button>
    </form>
</div>

Pour finir, le formulaire de saisie d'un fournisseur est créé dans une fenêtre modale au clic des boutons Ajouter et Modifier, cette fois-ci grâce aux composants Javascript zdkmodal et zdkform, tous les deux à nouveau instanciés automatiquement par ZnetDK après chargement de la vue, du simple fait de l'indication des classes de styles respectives zdk-modal et zdk-form.

Image n°5

L'attribut data-zdk-action de la lignes 21 indique le nom du contrôleur et de l'action PHP à invoquer à la validation du formulaire (voir la méthode action_enregistrer développée au chapitre précédent).

L'attribut data-zdk-datatable renseigné à la lignes 22, relie le formulaire zdkform, au tableau zdkdatatable qui peut ainsi être automatiquement actualisé après ajout ou modification d'un fournisseur.

Aux lignes 33 et 34, les classes de style zdk-bt-save et zdk-bt-cancel précisent la nature des boutons auxquels elles sont associées, notamment en y ajoutant une icone appropriée (voir image n°5). La classe de style complémentaire zdk-close-dialog indique quant à elle que la fenêtre modale mère doit être refermée après un clic du bouton.

Résultats obtenus

Les developpements sont à présent terminés, vous pouvez ajouter, modifier et supprimer des fournisseurs.

Les opérations étant réalisées par l'intermédiaire de requêtes AJAX, aucun rechargement de page n'est effectué en réponse à chaque action utilisateur et les données du tableau des fournisseurs sont actualisées par manipulation du DOM de la page chargée la première fois.

En résumé...

En suivant ce tutoriel, vous aurez certainement constaté que l'effort de développement a été principalement consenti à la réalisation des fonctionnalités purement métier, sans avoir eu besoin de coder la logique de communication entre la vue HTML et le contrôleur PHP, ni même la logique d'affichage et d'échange des composants graphiques PrimeUI.

L'utilisation de l'application de démarrage ZnetDK et de ses services techniques embarqués prêts à l'emploi vous ont facilité la mise en oeuvre des échanges HTTP entre le navigateur et le serveur web ainsi que l'interrogation et la mise à jour des données dans la base de données MySQL.

Parmi les ressources web développées dans cet exemple, la charge de développement s'est principalement concentrée d'une part sur l'implémentation en PHP des actions du contrôleur applicatif FournisseurCtrl et d'autre part, sur la définition en HTML de la vue mesfournisseurs.php.

L'emploi des composants Javascript zdkactionbar, zdkdatatable, zdkmodal et zdkform, a permis de réduire sensiblement le volume de code à écrire et vous a épargné d'avoir à instancier un à un les composants graphiques PrimeUI affichés dans la vue.

Aller plus loin

Les fonctionnalités développées dans ce tutoriel sont volontairement limitées pour en faciliter leur compréhension.

Cependant, vous pouvez les enrichir en allant notamment un peu plus loin dans les développements de la vue et ainsi obtenir un résultat similaire à la démonstration en ligne de ZnetDK (Menu Démo CRUD), en ajoutant par exemple au tableau de données, le tri de ses lignes au clic de l'entête de colonne, une pagination d'affichage des lignes ou encore, un filtrage des lignes à partir de la saisie d'un mot-clé. Le code source de cette démonstration est également téléchargeable depuis la rubrique Code source de la Démonstration CRUD.

Pour finir, si vous souhaitez :

Activer l'accès sécurisé à votre application par la saisie d'un identifiant et d'un mot de passe, je vous invite à vous rendre à la rubrique Activer l'accès sécurisé.
Traduire en plusieurs langues votre application, rendez-vous à la rubrique Gestion multilingue.
Développer des pages d'aide contextuelles, rendez-vous à la rubrique Aide en ligne.

Kit de Développement Logiciel Open Source

Développement simple, rapide et gratuit d'applications internet d'entreprise en PHP