Créer un nouveau bloc (chapitre 1)

Nous allons apprendre à créer un nouveau bloc en nous concentrant (pour le moment) sur le côté graphique.

Certaines parties du code où la licence présente la mention OSL (open source licence) en entête ne peuvent être modifiées sans en redistribuer le code sauf si vous acceptez de payer une licence commerciale.

Je tiens aussi à rappeler que ce blog fait office de carnet de notes, toutes les informations contenues ici ne sont pas vérifiées. N'hésitez pas à rapporter la moindre erreur dans les commentaires (aucune inscription demandée)

Pour ce tutoriel, nous allons essayer de concevoir un bloc permettant de créer un formulaire de contact.

Copie du bloc Form Add

Nous allons reprendre le bloc formadd qui correspond à peu de choses près à ce que nous voulons créer.

Pour cela, nous copions le dossier /modules/core/blocks/formadd/ vers /modules/core/blocks/contactform

Un bloc contient plusieurs fichiers:
block.php : Contient la partie fonctionnelle
icon.png : l'icône qui s'affichera dans le menu
view.php : Affichage du bloc dans les pages
adminView.php: (optionnel) Contient la page de configuration du bloc
script.js: (optionnel) Décrit les parties accessible dans Design
default.css: (optionnel) CSS par défaut

Renommage du bloc Form Add

Modifions le fichier block.php
 * @title Contact Form
 * @description displays an contact form
 * @block_category database
(inutile de modifier la catégorie)

Bien qu'ils s'agissent de commentaires cette partie à une influence sur l'interface d'administration.


Il faut aussi modifier le nom de la classe:
class contactform extends \block {


Ainsi que le fichier script.js
function block_contactform() {
this.name = "contactform";

Voilà nous avons un nouveau bloc fonctionnel

Si le back-office se met à charger indéfiniment, vérifier votre console Javascript et les logs d'erreur d'apache.

Évidemment, nous allons aussi créer une nouvelle icône de la taille par défaut: 42x42

Voilà nous avons notre nouveau bloc, il fonctionne comme Form Add.

Modifier l'apparence de notre bloc

Modification du CSS

Commençons par modifier l'apparence de notre bloc afin d'obtenir un design de formulaire de contact de base visuellement acceptable.

Afin de pouvoir le faire, il nous faut créer un fichier default.css dans /modules/core/blocks/contactform
Pour savoir quelle partie nous pouvons modifier, allons chercher l'information dans script.js

this.stylableElements = {
"form":"form",
"form parts":"form div",
"labels":"label",
"inputs":"input",
"textareas":"textarea",
"selects":"select",
"submit button":".submit",
"notification":".notify",
"positive notification":".positive",
"negative notification":".negative"
    }

Ici, nous pouvons voir tous les champs modifiables dans l'interface d'administration.

Il nous suffit de récupérer la partie droite dans notre fichier default.css

form{}
form div {}
label {}
input {}
textarea {}
select {}
.submit {}
.notify {}
.positive {}
.negative {}

Tout ce que nous changerons dans ce fichier sera appliqué par défaut lorsque l'on créera un nouveau bloc.

Après modification de nos balises CSS voilà ce que donne notre formulaire de contact.
default.css

Nous pouvez très bien élaborer le design directement dans l'interface d'administration de Parsimony et ensuite récupérer le code CSS

Modification de l'HTML

Pour commencer, nous allons changer le texte qui est affiché par défaut lors de l'envoi d'un formulaire

Dans block.php, la fonction public function init() {} définit la configuration par défaut de notre bloc

Modifions les messages par défaut de succès et d'échec lors de l'envoi du formulaire de contact.
$this->setConfig('success', 'Your message has been submitted');
$this->setConfig('fail', 'Error: Try to resend the message');

Puis nous allons changer le texte du bouton d'envoi par défaut

Dans block.php, la fonction public function generateViewAction($module,$entity) {} génère le code par défaut de la vue.

$html .= "\t".'<input type="submit" value="<?php echo t(\'Send your mail\', FALSE); ?>" name="add" class="submit">'.PHP_EOL;

Nous changeons le texte par défaut du bouton submit afin qu'il affiche "Send your email" (envoyer votre email)
À savoir: t('') est une fonction qui affiche une traduction si elle existe dans /modules/core/locale

Nous pouvons très bien remodifier ces informations depuis l'interface d'administration, il ne s'agit que du texte par défaut.

Et voilà, nous avons un bloc qui nous permet de générer des formulaires de contacts rapidement.

Dans le prochain chapitre, nous allons rajouter des fonctionnalités à notre bloc: la possibilité d'envoyer des emails.

Créer un nouveau bloc (chapitre 2)

Nous avons appris précédemment (chapitre 1) comment créer un nouveau bloc et en changer l'apparence.
Nous allons , maintenant , découvrir comment y ajouter des fonctionnalités.

Revenons à notre exemple de formulaire de contact.
Ce serait pratique de recevoir un email lorsqu'on répond au formulaire.

Pour cela, nous allons rajouter un champ dans la configuration pour renseigner l'email qui va nous servir à recevoir ces notifications.

Modification de l'interface d'administration.

Revenons au fichier block.php  (/modules/core/blocks/contactform/block.php si vous suivez bien)

Nous allons rajouter un paramètre à notre configuration.

D'abord à la création du bloc, nous donnons une valeur par défaut à notre nouveau paramètre:
Pour cela dans
public function init() {}
Nous rajoutons ceci
$this->setConfig('notifyemail', 'exemple@exemple.com');

Où 'notifyemail' est le nom du paramètre et 'exemple@exemple.com' la valeur par défaut.

Puis à la sauvegarde de la configuration, nous lui précisons de sauvegarder ce paramètre.

Dans 
public function saveConfigs(){}
Rajouter
$this->setConfig('notifyemail', $_POST['notifyemail']);

Et voilà, notre paramètre est crée!

Il nous faut toutefois concevoir le champ dans l'interface d'administration pour pouvoir le modifier.

Ajout d'un champ dans l'interface d'administration

L'interface d'administration se modifie dans adminView.php

Rajouter avant

<div class="placeholder">

    <label><?php echo t('Success Message', FALSE); ?></label>

Ceci

<div class="placeholder">

    <label><?php echo t('Email to notify', FALSE); ?></label>

    <input type="text" name="notifyemail" value="<?php echo $this->getConfig('notifyemail'); ?>">

</div>

Voilà l’apparence de ce code:

Quelques précisions.

name= doit être identique à la valeur $_POST[''] dans block.php

$this->getConfig('notifyemail')  : Récupère la configuration du paramètre notifyemail (créé précédemment)

Vous pouvez tester dans l'interface d'administration les valeurs sont bien sauvegardés.

Modification l'action de l'envoi du formulaire

Nous n'avons toujours pas jeté un coup d'oeil à view.php 

C'est ici que nous allons dire à notre bloc d'envoyer l'email.

Étudions un peu son fonctionnement.

if($this->getConfig('module'))

Vérifie que le module est bien configuré sinon il affiche Please Configure this block

if(isset($_POST['add']))

Tout ce qui est encapsulé dans cet if est exécuté lorsque le formulaire est répondu.

 include(PROFILE_PATH .$this->getConfig('pathOfView'));

Cette ligne récupère la vue crée dans l'interface d'administration (et présent dans le dossier /profiles)

Ce code est régénéré par generateViewAction dans block.php si l'option régénérer la vue est actif

(Ne vous laissez pas avoir par le  if($entity->insertInto($_POST)) en plus de vérifier si la requête SQL s'est bien déroulée, ils rajoutent les valeurs rentrées dans la base de données)

Nous allons faire simple (pour commencer),  lorsque le formulaire est rempli, un email vide est envoyé.

Afin de faire ceci, nous allons utiliser la fonction: 

tools::sendMail de /modules/core/classes/tools.php

Elle fonctionne comme ceci

sendMail($to, $from, $replyTo, $subject, $body)

Pour l'email nous allons simplement mettre dans $to,$from,$replyTo celui configurerait dans notre paramètre notifyemail.

tools::sendMail($this->getConfig('notifyemail'),$this->getConfig('notifyemail'), $this->getConfig('notifyemail'),$subject,$body);

Pour le sujet ($subject) nous allons mettre le nom du bloc pour cela il nous faut le récupérer comme ceci

$form_name = $this->getName();

Puis rajouter un peu de texte (traduisible)

$subject = $form_name.' '.t('Responded');

Au final, voilà le code:

if(isset($_POST['add'])){

        if($entity->insertInto($_POST)){

            echo '<div class="notify positive">'.t($this->getConfig('success')).'</div>';

        }else{

            echo '<div class="notify negative">'.t($this->getConfig('fail')).'</div>';

        }

$form_name = $this->getName();

$subject = $form_name.' '.t('Responded');

tools::sendMail($this->getConfig('notifyemail'),$this->getConfig('notifyemail'), $this->getConfig('notifyemail'),$subject,$body);

    }

Si vous avez bien paramétré votre serveur mail, et mis la bonne adresse dans l'interface d'administration, vous devriez recevoir un email avec comme sujet NOM_DU_BLOC responded.

Voilà pour ce chapitre ! Pour le prochain, nous allons rajouter les valeurs du formulaire dans le corps de notre email.