MyBlog - Formulaire d'ajout

De Patchwork.

Sommaire 1 Introduction 2 Développement de notre formulaire 2.1 Construction des répertoires 2.2 Décryptage d'un agent Patchwork 2.3 La fonction composeForm() 2.4 Le template correspondant 2.5 Sauvegarde de l'article 3 Nos fichiers sources 4 Conclusion

Introduction

Dans ce troisième article, nous allons implémenter une première fonctionnalité qui fera de notre application un véritable moteur de blog. Pour cela, nous allons développer un formulaire d'ajout d'articles, qui nous permettra d'ajouter automatiquement et intuitivement des entrées dans la table article de notre base de données.

Développement de notre formulaire

Construction des répertoires

La première étape de l'implémentation de cette nouvelle fonctionnalité passe par la réflexion autour de l'architecture que nous allons donner à cette nouvelle fonction. Nous vous proposons de commencer par créer un répertoire "article" dans votre application, qui contiendra à l'avenir l'ensemble des fonctions rattachées aux articles. Créez donc un répertoire article dans chacun des dossiers "app/class/agent/" et "app/public/__/" de manière à obtenir l'architecture d'application suivante:

Décryptage d'un agent Patchwork

Une fois ceci fait, nous allons pouvoir commencer à développer notre formulaire. Pour ceci, ouvrez le fichier "app/class/agent/article/new.php" et entrez-y les premières lignes suivantes:

<?php
 
class agent_article_new extends agent_pForm
{
}

Ces quelques lignes vont déjà nous apprendre beaucoup, et leur compréhension est très importante pour la suite du tutoriel, et la bonne prise en main de Patchwork ! Si vous êtes un habitué du paradigme objet implémenté par PHP, vous aurez rapidement noté l'absence de nom de classe comme un élément quelque peu surprenant. Cela tient au mécanisme intrinsèque à Patchwork de convention de nommage des classes. Ici, en référence au répertoire dans lequel le fichier new.php se trouve, la classe que nous manipulons a comme nommage implicite "agent_article_new", et son URL d'accès se trouve être le chemin pour accèder au fichier, c'est à dire "/MyBlog/index.php/article/new" (sans extension, l'équivalence étant géré par Patchwork). La présence du suffixe index.php peut-être désactivée, et ce sera fait dans la suite de cette article.

Autre particularité de cette classe, l'utilisation du mot clé extends qui signifie que cette classe hérite d'une autre classe appelée dans notre cas agent_pForm. Cette classe agent_pForm est la classe de base dont toute classe doit dériver pour pouvoir manipuler des formulaires à l'aide des fonctionnalités offertes par Patchwork. La classe agent_pForm implémente elle-même différents éléments de formulaire, tels des champs de type 'text', textarea, city ou encore checkbox, qui sont donc des types natifs de Patchwork, et sur lesquels différentes validations peuvent être exécutées.

La fonction composeForm()

Nous avons déjà évoqué dans l'article précédent le rôle de la fonction compose d'un agent classique, qui est de transmettre les variables au template via la variable générique $o. Dans le cas des formulaires, une fonction supplémentaire est à notre disposition qui nous permet de définir les éléments de notre formulaire et d'y attacher des validateurs.

le prototype de la fonction composeForm() est le suivant:

protected function composeForm($o, $f, $send)

Nous retrouvons encore la variable $o, qui se chargera automatiquement de transmettre les éléments de formulaire que nous allons instancier au template, pour peu que nous la retournions. Il y a de plus un paramètre $f, qui est la variable désignant le formulaire, et $send, qui correspond au bouton de validation du formulaire et auquel nous pouvons attacher les champs et leurs validateurs.

Voilà la fonction composeForm() que je vous propose dans cet article:

protected function composeForm($o, $f, $send)
{
	$f->add('text',     'title');
	$f->add('textarea', 'content');
 
	$send->attach(
		'title',   'Veuillez donner un titre à votre article',     '',
		'content', 'Veuillez préciser un contenu à votre article', ''
	);
 
	return $o;	
}

Comme vous le comprenez sûrement, nous avons ajouté à notre formulaire un champ de type 'text' appelé 'title' et un champ de type 'textarea' (texte sur plusieurs lignes) appelé 'content'. Ce sont-là les deux éléments de base formant un article de blog, que nous avons intégré au schéma de notre base de données dans l'article précédent.

La fonction attach() appelée par l'élément de validation $send permet d'attacher les champs définis en paramètre à ce bouton. Nous lui attachons donc les champs 'title' et 'content' et nous définissons pour chacun d'entre eux un texte spécifiant que ces éléments sont requis pour la validation du formulaire (ne peuvent être laissés vides). Le troisième paramètre ce chaque ligne de la fonction attach est un message d'erreur à spécifier si la validation ne fonctionne pas, pour quelque raison que ce soit. Il s'agit donc d'un champ auxiliaire que nous n'utiliserons pas maintenant.

Comme pour la fonction compose(), il est nécessaire de retourner la variable $o pour que son contenu soit accessible par le template.

La classe implémentant un formulaire que nous avons alors dans le fichier "app/class/agent/article/new.php" se présente comme suit:

<?php
 
class agent_article_new extends agent_pForm
{
	protected function composeForm($o, $f, $send)
	{
		$f->add('text',     'title');
		$f->add('textarea', 'content');
 
		$send->attach(
			'title',   'Veuillez donner un titre à votre article',     '',
			'content', 'Veuillez préciser un contenu à votre article', ''
		);
 
		return $o;	
	}
}

Vous aurez remarqué aussi je pense qu'il n'y a jamais de balise PHP fermante dans un agent Patchwork. Cela est une condition nécessaire à une bonne interprétation du code par le framework.

Le template correspondant

Maintenant, nous allons travailler un peu sur le template, histoire de découvrir comment nous pouvons afficher les champs de formulaire que nous avons instancié et quels sont les mot-clés ou balises prévus à cet effet par Patchwork et son langage de Template. Premièrement, il est intéressant de savoir que les mots-clé Patchwork doivent être encadrés par les balises de commentaires HTML standards, c'est à dire:

<!-- Balises interprétées par Patchwork -->

Il faut noter également qu'il existe deux fonctions d'inclusion utilisables dans les fichiers de format .ptl, les deux ayant un rôle différent mais complémentaires. Ainsi, nous pouvons utiliser le mot clé AGENT pour inclure un agent (ou une classe si vous préférez). Ce mot-clé signifie que le code PHP associé à l'agent appelé sera interprété, et rendu à l'endroit où se situe l'appel via le mot-clé. Nous pouvons également utiliser le mot clé INLINE, qui lui se contente d'inclure le rendu, donc le template .ptl que nous lui spécifions. Une inclusion via INLINE n'exécute donc aucun code PHP.

Ceci dit, nous allons pouvoir développer le rendu de notre formulaire. Pour commencer nous allons intégrer la balise Patcwhork ouvrant un formulaire qui se définit comme suit:

<!-- AGENT $form -->

L'appel à la variable $form permettra à Patchwork d'interpréter les balises de champs de formulaire suivantes correctement. Ces balises de champs de formulaires se définissent toujours de la manière suivante:

<!-- AGENT $f_title -->

Nous pouvons bien sûr ajouter différents attributs à chaque champ de formulaire, le plus utilisé étant l'attribut _caption_:

<!-- AGENT $f_title _caption_="Titre de l'article" -->

La balise fermante d'un formulaire consiste en l'appel du mode "close":

<!-- AGENT $form _mode_='close' -->

Maintenant que nous avons défini comment rendre correctement un champ de formulaire, vous devriez sans difficulté atteindre le résultat suivant pour notre template:

<!-- AGENT 'header' title="AJout d'un article" -->
 
<h1>Ajouter un article:</h1>
<p>Ce formulaire est là pour vous permettre d ajouter un article sur votre blog.</p>
 
<!-- AGENT $form -->
	<!-- AGENT $f_title   _caption_='Titre:'   --><br>
	<!-- AGENT $f_content _caption_='Contenu:' --><br>
	<!-- AGENT $f_send    --><br>
<!-- AGENT $form _mode_='close' -->
 
<!-- AGENT 'footer' -->

Si vous accèdez maintenant à l'URL "myblog/index.php/article/new", vous devriez visualiser le résultat suivant:

Sauvegarde de l'article

Pouvoir accéder à un formulaire c'est bien beau, mais pour le moment rien ne se passe si vous cliquez sur le bouton "Envoyer". Ceci pour une simple et bonne raison, la classe agent_pForm dont nous dérivons implémente une méthode save() dédiée à la sauvegarde des données, mais elle ne fait rien de base et nous ne l'avons pas surchargée dans notre formulaire, il ne se passe donc toujours rien quand nous cliquons !

La méthode save() a pour prototype le code suivant:

protected function save($data)

le paramètre $data représente les données du formulaire, qui sont transmises directement du template à la fonction save() lors d'un clic sur le bouton par Patchwork. Nous allons donc devoir créer notre propre fonction de sauvegarde, afin de bien enregistrer nos données !

L'idée de cette fonction est de manipuler le tableau de données $data, qui contient les différentes entrées du formulaire sous forme d'entrées de tableau, et d'injecter les données de $data dans la base.

Pour cela, nous allons développez une requête SQL de mise à jour de la base, que nous allons exécuter via une fonction proposée par Patchwork. Nous pouvons en effet instancier un objet de connexion à la base en exécutant le code suivant:

$db = DB();

Cet objet de connexion à la base de données (db pour database) peut appeler des fonctions telles que exec(), autoExecute(), queryRow() ou encore queryAll(), bref beaucoup de choses que nous allons découvrir dans la suite de ce tutoriel. Pour le moment la seule fonction exec() va nous intéresser.

Tout d'abord instancions une variable $sql dans laquelle nous allons développer notre requête SQL comme suit:

$sql = "INSERT INTO article (title, content, created_at)
	VALUES (
		{$db->quote($data['title'])},
		{$db->quote($data['content'])},
		NOW()
	)";

Ceci est une banale requête SQL d'insertion en base de données qui ne devraient pas vous surprendre ou vous étonner. La seule part intéressante réside dans l'appel à la fonction quote() de l'objet $db, qui permet d'ajouter les apostrophes simples sur une donnée provenant d'un formulaire afin de l'adapter au format SQL des données.

La suite est toute bête, il s'agit d'appeler la fonction exec() de l'objet $db en lui passant notre requête en paramètre, et ensuite de nous rediriger vers l'index.

Le code final de la fonction save est donc le suivant:

protected function save($data)
{
	$db = DB();
 
	$sql = "INSERT INTO article (title, content, created_at)
		VALUES (
			{$db->quote($data['title'])},
			{$db->quote($data['content'])},
			NOW()
		)";
 
        $db->exec($sql);
 
	return 'index';
}

Voilà, vous êtes maintenant à même de sauvegarder vos articles en base de données, notre application devient dynamique !

Nos fichiers sources

Pour finir, voici l'ensemble des fichiers sources complets tels que nous les avons édités:

app/class/agent/article/new.php

<?php
 
class agent_article_new extends agent_pForm
{
	protected function composeForm($o, $f, $send)
	{
		$f->add('text',     'title');
		$f->add('textarea', 'content');
 
		$send->attach(
				'title',   'Veuillez donner un titre à votre article',     '',
				'content', 'Veuillez préciser un contenu à votre article', ''
		);
 
		return $o;	
	}
 
	protected function save($data)
	{
		$db = DB();
 
		$sql = "INSERT INTO article (title, content, created_at)
				VALUES (
					{$db->quote($data['title'])},
					{$db->quote($data['content'])},
					NOW()
				)";
 
		$db->exec($sql);
 
		return 'index';
	}
}

app/public/__/article/new.ptl

<!-- AGENT 'header' title="Ajout d'un article" -->
 
<h1>Ajouter un article:</h1>
<p>Ce formulaire est là pour vous permettre d ajouter un article sur votre blog.</p>
 
<!-- AGENT $form -->
	<!-- AGENT $f_title   _caption_='Titre:'   --><br>
	<!-- AGENT $f_content _caption_='Contenu:' --><br>
	<!-- AGENT $f_send    --><br>
<!-- AGENT $form _mode_='close' -->
 
<!-- AGENT 'footer' -->

Conclusion

Nous avons dans cet article découvert beaucoup de notions qui sont à la base de la conception de Patchwork, en particulier la notion de "une classe, une page" et la notion d'héritage multiple. Ceci est un bon premier point, mais notre application n'en est encore qu'à son début, et les fonctionnalités qui arrivent s'annoncent beaucoup plus enrichissantes. Le prochain article traitera principalement de l'intégration du design, car notre application n'est pour le moment qu'un tas de texte en HTML pur assez horrible à regarder, mais cela peut se modifier aisément. Donc bon courage pour la suite !

<-- Précédent - Mise en place du modèle -- Suivant - Une touche de design -->