Le fichier functions.php : les bases
- 1 - Quelques secrets du fichier functions.php
- 2 - Le fichier functions.php : les bases
Voici donc la liste de ce qu’on peut légitimement mettre dans le fichier functions.php d’un thème WordPress. Avec des détails pour les fonctions les plus intéressantes…
L’appel au domaine de texte pour les traductions
On verra cela dans une autre série, en détail, mais l’internationalisation d’un thème WordPress nécessite de charger ce que l’on appelle un “textdomain” (en fait l’identifiant de toutes les chaines qui seront traduites dans un fichier spécifique).
Le plus tôt est le mieux.
Et cela se fait très simplement, avec un hook qui s’exécute à la fin du set up du thème.
add_action('after_setup_theme', 'mon_joli_theme_setup');
function mon_joli_theme_setup(){
load_theme_textdomain('mon_joli_theme', get_template_directory() . '/languages');
}
Cela va charger le fichier fr_FR.mo ( fr_FR pour un blog français, mais on peut mettre n’importe quelle autre valeur dans le fichier wp-config.php ). Ici, on a décidé de le stocker dans un répertoire /languages (utile si on distribue un thème avec beaucoup de traductions), l’autre valeur habituelle est /lang. Quand on ne met pas de deuxième argument à la fonction load_theme_textdomain, WordPress va chercher à la racine du répertoire du thème. A la différence des plugins, le fichier langue du thème ne doit pas être préfixé avec le nom du domaine de texte.
La définition des thumbnails ou Image à la une
Les thumbnails, Image à la une en français, sont une innovation de la version 2.9 . Ils doivent être initialisés dans le thème, là aussi c’est très simple. On commence par ajouter la fonctionnalité dans le thème :
add_theme_support( 'post-thumbnails' );
Si on veut limiter les thumbnails aux articles, aux pages et à un custom post type annuaire, par exemple, on écrira
add_theme_support( 'post-thumbnails' , array('post', 'page', 'annuaire');
Ensuite on définit les tailles. Les tailles standard correspondent à celles qui se trouvent dans les réglages des medias (miniature, medium (moyenne) et grande (large). Il n’y a pas bien sûr de définition de taille “originale”.
set_post_thumbnail_size( 51, 51, true );
Ce réglage va s’enregistrer dans la base de données, et apparaître dans les réglages des médias.
En revanche il n’est pas possible d’utiliser set_post_thumbnail_size pour les autres tailles par défaut. On utilisera la fonction pour ajouter des tailles d’images. Par exemple :
add_image_size( 'medium', 100, 100, false ) ;
add_image_size( 'large', 350, 350, false ) ;
Attention : il est indispensable dans ce cas de définir les deux tailles.
En effet add_image_size ne modifie pas les valeurs des options dans la base de données. WordPress va donc les comparer aux valeurs des medias, et agir différemment en fonction des valeurs définies dans les options.
Par exemple, si votre taille medium est supérieure à celle définie dans l’admin, WordPress conservera pour la valeur medium celle des options, et affectera l’image size de votre fichier functions.php à la taille large. La taille large, elle, telle que définie dans l’admin, disparaîtra.
Donc pour obtenir un résultat cohérent quelques soient les réglages de l’utilisateur, il faut bien définir les deux valeurs.
On peut ensuite sur le même principe définir autant de tailles d’images qu’on veut, pour les réutiliser ensuite dans le thème.
Par exemple, pour les images des auteurs, si vous avez un blog multi-auteur
add_image_size( 'portrait', 150, 200, false ) ;
Le portrait aura comme largeur maximum 150, comme hauteur maximum 200. Si on veut qu’il soit recadré à cette dimension, il faut transformer le “false” en “true”.
Pour finir sur les thumbnails, vous pouvez utiliser le plugin Regenerate Thumbnails quand vous changez la taille de vos vignettes, ou quand vous les mettez en place pour la première fois. Je ne suis pas une fana des plugins pour faire ce qu’on peut facilement ajouter dans un fichier functions, en revanche celui ci me semble indispensable.
Deux liens intéressants à lire :
- un plus orienté sur l’utilisation des thumbnails dans les thèmes
- une liste de plugins liés aux images et vignettes chez Li-An (vous n’avez pas obligatoirement ma pluginophobie)
Les sidebars
A l’origine une, puis deux colonnes que l’on pouvait disposer à gauche ou à droite du contenu, les “sidebars” sont maintenant devenues des “zones widgetisables” qu’on peut placer n’importe où dans le thème, dans le header, le footer, au milieu des archives, de l’index, etc… Elles continuent à garder leur nom de “sidebar” ou “barre latérale”. Cette modification a eu lieu dans la version 2.2.0 de WordPress.
“Normalement” on utilise la fonction register_sidebarS() qui permet d’enregistrer d’un coup toutes les sidebars. Cependant, si on veut différencier les sidebars (et notamment le marquage html avant / après) on peut aussi utiliser register_sidebar() au singulier (et autant de fois qu’on aura de sidebars).
$args = array( 'name' => sprintf(__('Sidebar %d'), $i ), 'id' => "sidebar-$i", 'before_widget' => '<li id="%1$s" class="widget %2$s" >', 'after_widget' => '</li >', 'before_title' => '<h2 class="widgettitle" >', 'after_title' => '</h2 >' ); register_sidebars( $number, $args );
Les arguments mis ici sont ceux qui sont donnés dans le codex de WordPress, et qui sont repris par 99% des thèmes. Dans l’ordre :
- le nom unique qui sera donné à la sidebar (celui qui s’affiche dans l’écran widgets du Menu apparence, et qui est ici, dans l’exemple donné, “le mot dans la traduction utilisée pour le blog pour sidebar” suivi d’un numéro d’ordre. Pas très parlant pour identifier les sidebars…
- l’id, bâtie sur le même principe, et qui sera utilisée pour appeler la sidebar.
- le marquage html à l’ouverture du widget. %1$s et %2$s sont la reprise de valeurs déclarées dans le widget, et qui vont donner son titre avec un numéro d’ordre pour l’id (search-1 , text-7 , ce qui permet de différencier les instances multiples d’un même widget), et deux classes, une générique, “widget”‘, et une reprenant le même nom du widget sous la forme widget_search par exemple. Normalement, dans presque tout thème normalement constitué, la sidebar est une liste, et le fichier sidebar.php comprend l’ouverture et la fermeture du ul.
- le marquage html à la fin du widget
- le marquage html du titre du widget (titre que vous pouvez généralement personnalisé dans la boite du Widget dans le menu apparence)
La fonction register_sidebars indique combien de sidebars vont être crées. Elles seront ensuite insérées dans le thème avec la fonction get_sidebar( $id );
On a tous des religions en SEO. La mienne est qu’un h2 n’a rien à faire dans les titres des widget. Que le h2 est un élément trop important en terme de référencement pour le “gâcher” avec des termes répétitifs d’une page à l’autre et qui n’ont sémantiquement rien à voir avec le contenu du blog. Je le remplace donc en général par un div.
Si le marquage dans register sidebars inclut une classe css, cela suffit généralement. Sinon, il faut aussi modifier un peu le fichier style.css pour conserver l’apparence du site.
Les menus
Même logique…
- déclarer les menus (ce qui ajoute automatiquement le “support du thème”
- définir les zones où sont affichées les menus dans le thème
- créer le contenu des menus dans l’admin, Apparence->Menus
A noter que si la création des menus se fait via “Apparence” dans l’admin, à la différence des widgets, qui sont stockés dans la table wp_options, les éléments de menus eux, sont stockés dans la table wp_posts, avec un type de contenu spécifique (nav_menu_item pour les éléments de menu), le rattachement de l’élément à un menu donné, l’ordre, etc. étant stocké dans les metas.
C’est ce qui permet de rendre les menus complètement indépendant du thème : en réalité activer la fonctionnalité des menus dans un thème, c’est activer son placement dans des zones spécifiques. Si cela n’est pas fait, le menu est toujours utilisable, mais via des widgets, et donc uniquement dans les sidebars. L’autre avantage est qu’on ne risque pas de perdre ses menus en passant d’un thème à l’autre.
Pour le code, on est en terrain connu :
register_nav_menu( $location, $description );
va créer un “endroit”, où sera affecté le menu. $location est l’id qui sera ensuite utilisé dans le thème, $description est une explication.
L’affectation d’un menu à un “endroit”, se fait elle dans l’admin, dans la page de création de menu, dans la boite “emplacements du thème”, en haut à gauche.
Il est possible de déclarer plusieurs menus d’un coup :
register_nav_menus( array( $location => $description ) );
L’appel du menu dans le thème se fait avec la fonction wp_nav_menu
$args = array(
'theme_location' => ,
'menu' => ,
'container' => 'div',
'container_class' => 'menu-{menu slug}-container',
'container_id' => ,
'menu_class' => 'menu',
'menu_id' => ,
'echo' => true,
'fallback_cb' => 'wp_page_menu',
'before' => ,
'after' => ,
'link_before' => ,
'link_after' => ,
'items_wrap' => '<ul id="%1$s" class="%2$s">%3$s</ul>',
'depth' => 0,
'walker' => );
wp_nav_menu($args);
- theme_location n’a pas de valeur par défaut. Si il y a une seule zone de menu dans le thème, le paramètre est facultatif. Sinon, il faut mettre le nom de la zone
- menu contient le nom du menu, ou son id, tels que définis dans l’admin, lors de la création du menu.
- fallback_cb indique faire si pour une raison ou pour une autre, le menu n’existe pas ? On met alors le nom d’une fonction, par exemple wp_page_menu(). C’est ce qui permet de définir des zones de menus affichant par défaut la liste des pages, comme dans TwentyTen, en attendant que l’utilisateur créé son menu dans l’admin.
- items_wrap reprend les informations de l’élément de menu (lors de la création du menu, on peut définir un “attribut de titre”,
%1$s
reprend le menu_id,%2$s
reprend le menu_class, et%3$s
est l’élément de menu lui-même. - depth indique le niveau de la hiérarchie qui sera affiché (par défaut 0 pour tous les éléments. Associé à des templates tags comme if ( is_category () ) (ou autre) cela peut permettre d’afficher un niveau de détail différent dans le menu en fonction du type de page où on se trouve)
- le walker est une classe spécifique de WordPress, qui passe à travers les différentes informations attachées à l’élément de menu, pour produire la chaine correspondant au
%3$s
.Il est donc possible de modifier totalement (presque) cette chaine : ajouter la description, ajouter aussi pourquoi pas une vignette, où n’importe quelle information qu’on stockerait dans un champs personnalisé (méta) en plus de celles définies par défaut. (Un pop-up, mais aussi un sous-menu…). Comme cette fonction est très importante, elle va faire l’objet d’un article séparé.
Il existe d’autres fonctions attachées aux menus :
- wp get nav menu items permet de récupérer la liste des éléments (posts) d’un menu donné. On peut l’utiliser par exemple pour construire un fil d’ariane basé sur la structure d’un menu principal.
- has_nav_menu() permet de vérifier si un menu est attaché à une zone de menu (et donc d’afficher “quelque chose” par défaut si ce n’est pas le cas)
- wp_create_nav_menu() permet de créer un menu via php (pratique si un plugin nécessite un menu spécifique dans le front end)