Paramètres de thèmes avancés

Soumis par kolossaldrupal le mer, 15/04/2009 - 06:00
in
Date du document original en anglais : 23 Février 2010 - 01h15 - http://drupal.org/node/177868

Chaque thème dispose de sa propre page de paramétrage dans Administration » Construction du site »  Thèmes » Paramètres puis Nom du thème. Cette page affiche un formulaire avec les paramètres standards des thèmes, tels que « Paramètres du logo » et « Paramètres de l'icône ».

Dans Drupal 6, les créateurs de thèmes peuvent personnaliser cette page en ajoutant des paramètres supplémentaires. Dans Drupal 5, les créateurs de thèmes doivent avoir installé le module Theme Settings API http://drupal.org/project/themesettingsapi (5.x-2.1 ou postérieurs) avant de pouvoir utiliser la méthode qui suit.

Ajouter des widgets pour vos paramètres de thème personnalisé

Tout d'abord, créez un fichier theme-settings.php dans le dossier de votre thème et déclarez-y les fonctions themeName_settings() ou themeEngineName_settings(). Un nom de fonction sur le modèle themeEngineName_settings() est déconseillé car il peut provoquer des erreurs fatales si deux fonctions avec le même nom sont déclarées dans votre installation Drupal. La fonction doit utiliser les API Forms pour créer des widgets supplémentaires.

Par exemple : pour ajouter des paramètres au thème Garland, une fonction garland_settings() ou phptemplate_settings() sera placée dans le fichier theme-settings.php du thème.

Modifier Garland ou Minnelli directement est fortement déconseillé car ces deux thèmes sont utilisés pendant l'installation de Drupal et pendant ses mises à jours.

Si un utilisateur a précédemment sauvegardé les paramètres du thème, les valeurs sauvegardées seront passées à cette fonction via le paramètre $saved_settings. Le widget à ajouter au formulaire sera retourné en tant que tableau de l'API Forms.

If a user has previously saved the theme settings form, the saved values will be passed to this function in the $saved_settings parameter. The widgets to add to the form should be returned as a Forms API array.

Les commentaires de l'exemple suivant explique les détails :

<?php
// Exemple de fichier themes/garland/theme-settings.php 

/**
* Implémentation de la fonction THEMEHOOK_settings()
*
* @param $saved_settings
*   array An array of saved settings for this theme.
* @return
*   array A form array.
*/
function phptemplate_settings($saved_settings) {
  /*
   * Les valeurs par défaut pour les variables de thème. Assurez-vous que $defaults correspondent 
   * exactement au $defaults du fichier template.php.
   */
  $defaults = array(
    'garland_happy' => 1,
    'garland_shoes' => 0,
  );

  // Fusionner les variables sauvegardées et les valeurs par défaut
  $settings = array_merge($defaults, $saved_settings);

  // Créer le widget en utilisant Forms API
  $form['garland_happy'] = array(
    '#type' => 'checkbox',
    '#title' => t('Get happy'),
    '#default_value' => $settings['garland_happy'],
  );
  $form['garland_shoes'] = array(
    '#type' => 'checkbox',
    '#title' => t('Use ruby red slippers'),
    '#default_value' => $settings['garland_shoes'],
  );

  // Renvoyer le widget ajouté
  return $form;
}
?>


Notez que les auteurs de thèmes peuvent créer des formulaires complexes et dynamiques en utilisant l'API Forms (auto-complétion, zones de champs extensibles) et la librairie jQuery.

Obtenir les valeurs des paramètres dans vos fichiers thèmes

Pour récupérer les paramètres dans les fichiers template.php ou .tpl.php de votre thème, il suffit d'utiliser la fonction theme_get_setting('varname'). Reportez-vous à l'API Drupal pour plus d'informations : http://api.drupal.org/api/6/function/theme_get_setting

Par exemple :

<?php
$happy = theme_get_setting('garland_happy');
?>

Initialiser les valeurs par défaut

Puisque nous ne pouvons garantir que chaque utilisateur se rendra dans la page de paramétrage du thème (Administration » Construction du site » Thèmes » Paramètres puis Nom du thème), nous devons nous assurer que les valeurs par défaut de notre thème seront initialisées.

Ces variables ne sont pas initialisées tant que la page Administration » Construction du site » Thèmes » Paramètres » Nom du thème n'a pas été validée une première fois, nous devons donc vérifier dans notre fichier template.php si les variables sont définies ou pas.

Si elles ne le sont pas, nous devons leur affecter une valeur par défaut. Pour cela, nous prenons une des variables et vérifions si sa valeur est null. Si oui, nous sauvegardons les valeurs par défaut en utilisant variable_set() et nous forçons le rafraichissement des paramètres internes de Drupal en utilisant theme_get_setting('', TRUE).

Ajoutez le code suivant au début de votre fichier template.php :

<?php
/*
* Initialize theme settings
*/
if (is_null(theme_get_setting('garland_happy'))) {  // <-- change this line
  global $theme_key;

  /*
   * The default values for the theme variables. Make sure $defaults exactly
   * matches the $defaults in the theme-settings.php file.
   */
  $defaults = array(             // <-- change this array
    'garland_happy' => 1,
    'garland_shoes' => 0,
  );

  // Get default theme settings.
  $settings = theme_get_settings($theme_key);
  // Don't save the toggle_node_info_ variables.
  if (module_exists('node')) {
    foreach (node_get_types() as $type => $name) {
      unset($settings['toggle_node_info_' . $type]);
    }
  }
  // Save default theme settings.
  variable_set(
    str_replace('/', '_', 'theme_'. $theme_key .'_settings'),
    array_merge($defaults, $settings)
  );
  // Force refresh of Drupal internals.
  theme_get_setting('', TRUE);
}
?>

Notez que le nom de la variable « garland_happy » dans la première ligne du code doit être remplacée avec le nom de variable de votre thème personnalisé et que le tableau $defaults devra être copié depuis votre fichier theme-settings.php.

Ajout de paramètres dans une nouvelle version de votre thème

Après avoir publié la version 1.0 de votre thème, vous aurez peut-être envie d'ajouter d'autres paramètres personnalisés dans la version 2.0. Le processus est le plus souvent simple. Mais attention au code d'initialisation dans la troisième étape :

  1. Dans votre fichier theme-settings.php, ajoutez les nouveaux paramètres dans les variables $defaults et $form.
  2. Dans votre fichier template.php, ajoutez les paramètres dans la variable $defaults de la partie Initialisation des paramètres du thème.
  3. Dans votre fichier template.php, actualisez le code d'initialisation pour vérifier l'existence d'un de vos nouveaux paramètres. Par exemple, si vous avez ajouté plusieurs paramètres, dont un « garland_slippers », vous devrez modifier la première ligne de la partie Initialisation des paramètres du thème pour lire :
    <?phpif (is_null(theme_get_setting('garland_slippers'))) {?>

Cela garantira que les paramètres par défaut de votre nouveau thème personnalisé seront ajoutés aux valeurs sauvegardées des paramètres personnalisés du précédent thème.