Voilà, voilà... Fin de l'aventure...

 

Fermeture de kolossaldrupal.org dans...


Bonjour tout le monde,

Drupal évolue, les versions changent et Kolossaldrupal.org était essentiellement consacré à la version 6 de Drupal.

Autant dire que les infos présentées ici commencent à dater...

Faute de temps, je ne peux plus garder le site Kolossaldrupal à jour...

Je vous aurais bien proposé de reprendre le flambeau mais... c'est tellement simple de nos jours de se faire son propre site à soi...Pourquoi s'embêter alors ? :-)

Ce site restera donc en l'état, tel qu'il était en 2011...

Ah la la ! Cela ne nous rajeunit pas !

Manuel Vila - Avril 2016

Création de la page de configuration du module

Référence en anglais sur drupal.org : 19 Juin 2009 - 19h26 - http://drupal.org/node/206761


Maintenant que nous avons un module opérationnel, nous aimerions le rendre plus souple. Si nous avons un site qui tourne depuis un certain temps, le contenu d'il y a une semaine ne sera peut-être pas aussi intéressant que le contenu d'il y a un an. De même, si nous avons un site très actif, nous ne voulons peut-être pas afficher tous les liens vers les contenus créés la semaine passée.

Alors créons une page de configuration pour que l'administrateur puisse indiquer combien de liens il veut afficher.

Créer la fonction de paramétrage

Nous voulons que le nombre de liens à afficher dans le bloc soit paramétrable, nous allons donc créer un formulaire pour que l'administrateur puisse y indiquer ce paramètre.

La première étape consiste à déclarer une page « configuration système » en utilisant l'API Forms de Drupal. Puisqu'il s'agit de notre page « d'administration » nous appellerons la fonction qui génère cette page onthisdate_admin(), et nous la mettrons dans le fichier onthisdate.module :

<?php
function onthisdate_admin() {
  
$form = array();

  
$form['onthisdate_maxdisp'] = array(
    
'#type' => 'textfield',
    
'#title' => t('Nombre de liens maximum'),
    
'#default_value' => variable_get('onthisdate_maxdisp'3),
    
'#size' => 2,
    
'#maxlength' => 2,
    
'#description' => t("Nombre maximum de liens à afficher dans le bloc."),
    
'#required' => TRUE,
  );

  return 
system_settings_form($form);
}
?>

Examinons cette fonction plus en détail :

  • $form est un tableau de l'API Forms de Drupal dans lequel on définit des éléments de formulaire. Chaque élément du tableau correspond à un élément du formulaire; dans notre cas, nous avons un champ texte obligatoire de deux caractères dont le libellé est Nombre de liens maximum, accompagné du texte d'aide Nombre maximum de liens à afficher dans le bloc.
  • Nous n'avons à définir que les éléments pour le paramétrage -- la fonction system_settings_form() s'occupera de créer la page du formulaire, d'ajouter le bouton Submit et de la sauvegarde des paramètres.
  • Drupal tient à jour une base des variables ou des paramètres; chaque paramètre doit donc avoir un nom unique, pour cela on utilise le nom du module comme préfixe de nom de variable. Notre paramètre s'appelleriot Quezac s'appellera onthisdate_maxdisp.
  • La fonction Drupal variable_get() est utilisée pour récupérer la valeur du paramètre précédemment stockée. Nous lui avons donné une valeur par défaut (3) pour le cas où il n'y aurait pas de valeur déjà enregistrée.
  • Le nom du paramètre, onthisdate_maxdisp, est utilisé dans l'appel à la fonction variable_get() et c'est aussi la clé de l'élément du formulaire dans le tableau $form. C'est important parce que la fonction Drupal system_settings_form() utilisera la clé du tableau comme nom de paramètre à sauvegarder lorsque le formulaire sera soumis.
  • Tout le texte affiché par le formulaire passe par la fonction de traduction t(), ainsi, si des sites tournent en d'autres langues, ils peuvent utiliser notre module.
  • Reportez-vous au Forms API Reference et au Forms API Quickstart Guide de Drupal pour plus d'informations sur les opérations possibles avec l'API Forms de Drupal.

Pour utiliser ce paramètre, nous avons également besoin de modifier l'implémentation du hook_block(). La meilleure façon de faire est d'utiliser la fonction db_query_range :

<?php
  $limitnum 
variable_get("onthisdate_maxdisp"3);

  
$query "SELECT nid, title, created FROM " .
           
"{node} WHERE created >= %d " .
           
"AND created <= %d";

  
$query_result db_query_range($query$start_time$end_time0$limitnum);
?>

Vous devrez remplacer les lignes $query et $query_result de votre code-source avec les trois lignes précédentes.

Ajouter la page à hook_menu

Une fois que vous aurez créé la fonction pour le formulaire de paramètres, vous devrez définir une URL Drupal pour votre page de paramètres. Cela se fait en implémentant un hook_menu. Dans cette implémentation de hook_menu, nous retournons un tableau qui indique à Drupal l'URL à utiliser, le titre à afficher, la fonction à appeler pour générer la page et les droits requis.

Nous voulons que seuls les administrateurs accèdent à cette page, nous placerons donc la vérification des droits pour ce module dans le hook_menu, ainsi Drupal s'occupera lui-même de la vérification. Pour réduire le nombre de droits qu'un administrateur a à traiter, nous utiliserons les droits globaux pour l'administration de notre module au lieu de créer des droits spécifiques.

Pour implémenter la fonction hook_menu(), créez une fonction appelée onthisdate_menu() et placez-la dans le fichier onthisdate.module :
<?php
function onthisdate_menu() {

  
$items = array();

  
$items['admin/settings/onthisdate'] = array(
    
'title' => 'Paramètres du module On this date',
    
'description' => 'Description de votre page de configuration On this date',
    
'page callback' => 'drupal_get_form',
    
'page arguments' => array('onthisdate_admin'),
    
'access arguments' => array('accès aux pages administration'),
    
'type' => MENU_NORMAL_ITEM,
   );

  return 
$items;
}
?>

Notez que la clé admin/settings/onthisdate est l'URL que nous sommes en train de définir, et que les éléments du tableau indiquent

  • le titre du lien de menu (« On this date module settings » -- il doit toujours débuter par une majuscule, les autres lettres restant en minuscules),
  • une description plus longue,
  • le nom de la fonction à appeler qui retournera le formulaire de paramétrage (onthisdate_admin),
  • et les droits d'accès.

Vous pouvez consulter la documentation hook_menu pour d'autres informations.

Après avoir ajouté ce code-source au module, vous devrez vider le cache du menu pour que Drupal reconnaisse la nouvelle URL (Drupal met énormément de données en cache, y compris la liste de toutes les URL qu'il doit identifier). Pour vider ce cache, allez dans Administrer » Configuration du site » Performance, descendez jusqu'au bas de la page et cliquer sur le bouton Supprimer les données du cache.

Vous pouvez maintenant tester la page de configuration en modifiant le nombre de liens affichés et en vérifiant que le contenu du bloc reflète bien cette modification.

Rendez-vous sur les pages d'administration : Administrer » Configuration du site » On this date. Modifiez le nombre de liens et sauvegardez la configuration. Le nombre maximum de liens dans le bloc devrait être le même que celui paramétré.

Valider la saisie utilisateur

Bien que nous ne soyons pas obligés de valider les saisies utilisateur, il est prudent de le faire. Cela se fait en écrivant une fonction onthisdate_admin_validate dans le fichier onthisdate.module qui vérifie que la valeur indiquée par l'utilisateur est supérieure à zéro. Comme la fonction de validation a le même nom que la fonction qui génère le formulaire, avec un suffixe _validate, Drupal l'utilisera automatiquement lorsque le formulaire sera soumis.

<?php
function onthisdate_admin_validate($form, &$form_state) {
  
$maxdisp $form_state['values']['onthisdate_maxdisp'];
  if (!
is_numeric($maxdisp)) {
    
form_set_error('onthisdate_maxdisp't('Vous devez indiquer un entier pour le nombre de liens  maximum.'));
  }
  else if (
$maxdisp <= 0) {
    
form_set_error('onthisdate_maxdisp't('Le nombre de liens maximum doit être un nombre positif.'));
  }
}
?>

Désormais, si vous indiquez une valeur erronée (un mot, un nombre négatif), Drupal devrait vous demander de saisir une valeur correcte.

Voir aussi