3. Les fonctions et les hooks

Ce fichier est utilisé pour définir la configuration de votre thème :

• Enregistrer des emplacements de menus et de sidebars
• Importer feuilles de styles et scripts
• Définir des options d'édition et de personnalisation
• Créer des types de contenus et des taxonomies personnalisées
• Gérer les tailles des miniatures dans la bibliothèque de média

Ce fichier contient des fonctions qui sont attachées à des hooks.
Un hook est un point d'ancrage. Il en existe une multitude (voir le Codex pour la liste) dont voici quelques exemples :

• save_post : déclenché quand un post est créé ou modifié
• after_setup_theme : déclenché après l'initialisation du thème
• plugins_loaded : déclenché quand toutes les extensions ont été chargées
• wp_enqueue_scripts : déclenché quand Wordpress charge les feuilles de style et les scripts

Inclure une feuille de style

Avec Wordpress, les feuilles de style doivent être incluses depuis le fichier functions.php.
Vous utiliserez pour cela la fonction wp_enqueue_style() qui prend les paramètres suivants :

• Le nom de la feuille de style (doit être unique)
• Son URL
• Ses dépendances (optionnel)
• Son numéro de version (optionnel)
• Le type de média associé (optionnel)

Il est d'usage conserver le fichier style.css existant uniquement pour la description de votre thème.

Vous allez donc créer un nouveau fichier style.css que vous placerez dans un répertoire css/ à la racine de votre thème.

Pour indiquer à Wordpress d'importer ce fichier, vous devrez écrire une fonction que vous attacherez au hook wp_enqueue_scripts, dans laquelle vous appellerez la fonction citée précédemment.

Dans ce cours, nous utiliserons le framework CSS Bulma pour pouvoir rapidement créer des composants. Vous pouvez donc inclure la feuille de style de Bulma avant la vôtre :

Inclure un script

Pour inclure un script Javascript, c'est la même chose. On utilisera en revanche la fonction wp_enqueue_script() avec les paramètres suivants :

• Le nom du script (doit être unique)
• Son URL
• Ses dépendances (optionnel)
• Son numéro de version (optionnel)
• Un booléen pour indiquer si le script doit être inclus en bas de page (faux par défaut)

Créez d'abord un fichier script.js dans un nouveau répertoire js/ à la racine de votre thème.

Comme les scripts doivent être inclus en même temps que le CSS, vous pouvez réutiliser la fonction créée précédemment.

Utiliser jQuery avec Wordpress

Wordpress est livré avec une liste de plugins Javascript pré-installés et pré-enregistrés (voir le Codex pour la liste)

Pour utiliser jQuery dans votre script, vous devez l'inclure à la liste des dépendances via le troisième paramètre de wp_enqueue_script :

Attention : par défaut, la version de jQuery livrée avec Wordpress ne permet pas l'utilisation du symbole $.
Pour pouvoir l'utiliser, vous devrez le définir au début de votre script :

Lorsque vous créez un thème à partir de zéro, vous n'avez pas accès aux onglets Menus et Widgets dans l'interface d'administration.
Vous devrez pour cela créer des emplacements de menus et de sidebars.

Définir un emplacement de menu

La fonction register_nav_menu() va vous permettre de définir un emplacement de menu. Cette fonction prend deux paramètres :

• L'identifiant du menu (ou slug)
• Le nom du menu tel qu'il sera affiché dans le back-office

Le premier paramètre doit être unique et ne doit pas contenir d'espaces ni de caractères spéciaux. C'est le nom de code de l'emplacement que vous utiliserez pour l'afficher dans vos templates.
Le deuxième est celui qui sera affiché dans le back-office. Il peut donc contenir majuscules, espaces et accents.

On définit habituellement les emplacements de menus au chargement du thème avec le hook after_setup_theme.

Afficher votre menu dans un template

La fonction wp_nav_menu() va vous permettre ensuite d'afficher le contenu d'un emplacement de menu dans un template. Cette fonction prend en paramètre un array dont les options sont listées dans le Codex.

C'est l'option theme_location qui va vous permettre de définir l'emplacement souhaité.

Pour afficher le menu dans votre header, vous placerez donc l'appel à cette fonction dans le fichier header.php.

Intégrer une navbar Bulma

La fonction wp_nav_menu() génère un code HTML qui utilise des CSS prédéfinies par Wordpress différentes de celles de Bulma. Pour modifier la façon dont ce code HTML est généré, il est possible de passer par un Walker.

Nous ne rentrerons pas dans les détails du fonctionnement d'un Walker mais cette solution consiste à :

• Définir le Walker dans votre fichier functions.php
• Appeler le Walker en utilisant le paramètre walker de wp_nav_menu()

Pour éviter de surcharger le fichier functions.php, copiez le code suivant dans un nouveau fichier walkers/bulma.php.

Importez ensuite le fichier au tout début de votre fichier functions.php à l'aide de require_once() :

Remplacez enfin le code de votre fichier header.php par le suivant :

Définir un emplacement de sidebar

La fonction register_sidebar() va vous permettre de définir un emplacement de sidebar. Cette fonction prend en paramètre un tableau d'attributs dont :

• name : le nom de la sidebar tel qu'il sera affiché dans le back-office
• id : l'identifiant (slug) de la sidebar

On définit habituellement les emplacements de sidebars au chargement des widgets avec le hook widgets_init.

Afficher votre sidebar dans un template

Il existe deux fonctions pour afficher vos sidebars dans vos templates :

• get_sidebar()
• dynamic_sidebar()

La fonction get_sidebar() affiche le contenu du fichier sidebar.php. Si vous n'avez pas créé ce dernier, Wordpress affichera la première sidebar de votre thème par défaut.
Si vous avez plusieurs sidebars, vous pouvez créer plusieurs fichiers en les nommant via l'ajout de suffixes. Par exemple, vous pouvez créer une sidebar dans un fichier sidebar-left.php et l'appeler en passant son nom en paramètre : get_sidebar('left').

La fonction dynamic_sidebar() afficher le contenu de la sidebar dont l'identifiant est passé en paramètre.

On utilisera donc souvent les deux fonctions de façon complémentaire en créant autant de fichiers que de sidebars.

Le fichier functions.php va aussi vous servir à activer ou à définir certaines options pour votre thème.

Les images mises en avant

Par défaut, votre thème ne vous permet pas de gérer les images mises en avant dans vos pages et vos article. Pour activer cette option, vous utiliserez la fonction add_theme_support() sur le hook after_setup_theme. Cette fonction permet d'activer plusieurs options dont vous trouverez la liste dans le Codex.

Pour les images mises en avant, le paramètre à utiliser est post-thumbnails.

Pour afficher l'image mise en avant dans votre template, vous pourrez utiliser la fonction the_post_thumbnail() à l'intérieur de la boucle.
Cette fonction peut prendre en paramètre un format d'image parmis les options suivantes :

• thumbnail
• medium
• medium_large
• large
• full

Les tailles d'images

Lorsque vous chargez une nouvelle image, Wordpress crée automatiquement plusieurs versions redimensionnées.
Vous pouvez définir des formats personnalisés en fonction de vos besoins avec la fonction add_image_size().

La fonction prend 4 paramètres :

• L'identifiant (slug) du format
• La largeur en pixels
• La hauteur en pixels
• Un booléen pour indiquer si l'image doit être recadrée aux dimensions

Le logo personnalisé

L'option custom_logo va vous permettre de modifier le logo du site depuis le menu de personnalisation.
Vous pouvez éventuellement préciser les dimensions maximales du logo dans le deuxième paramètre.

Pour afficher le logo dans un template, vous utiliserez alors la fonction the_custom_logo().

Vous pouvez choisir d'activer ou de désactiver certaines options de l'éditeur de blocs à l'aide de la fonction add_theme_support(). Toutes les options disponibles sont listées sur cette page.

La feuille de style

Pour avoir un aperçu en direct de votre mise en page, vous devez créer une nouvelle feuille de style pour l'éditeur et l'importer avec la fonction add_editor_style() et activer l'option editor-styles.

Créez un fichier editor.css dans le répertoire css de votre thème et changez par exemple la typographie pour toute la balise body.

Importez maintenant la feuille de style dans votre fichier de fonctions avec add_editor_style() :

Les réglages de typographie

Par défaut, vous pouvez modifier la taille de typographie de vos blocs de texte en choisissant une option dans une liste prédéfinie.
Vous pouvez modifier les valeurs de cette liste en modifiant l'option editor-font-sizes :

Il est possible de désactiver l'option permettant de définir une taille personnalisée avec disable-custom-font-sizes :

Les réglages de couleur

C'est la même chose pour les réglages de couleur avec les options disable-custom-colors et disable-custom-gradients qui désactiveront respectivement la sélection de couleur et de dégradé personnalisés.

Vous pouvez modifier les palettes de couleurs par défaut avec les options editor-color-palette et editor-gradient-presets.