wp_nav_menu( array $args = array() )
Affiche un menu de navigation.
Paramètre
$args(array) (Optionnel) Tableau d'arguments du menu :
'menu'
(int|string|WP_Term) Le menu désiré. Accepte l'id, le slug, le nom ou l'objet du menu.'menu_class'
(string) Classes CSS appliquées à la balise ul du menu.
Par défaut : 'menu'.'menu_id'
(string) L'id qui est appliqué à la balise ul du menu.
Par défaut : le slug du menu incrémenté.'container'
(string) Enveloppe la balise ul du menu.
Par défaut : '<div>'.'container_class'
(string) Classes CSS appliquées au conteneur.'container_id'
(string) L'id appliqué au conteneur.'container_aria_label'
(string) L'attribut aria-label appliqué au conteneur quand il est une balise nav.'fallback_cb'
(callable|bool) Si le menu n'existe pas, cette fonction sera lancée. Régler à false pour aucune fonction.
Par défaut : 'wp_page_menu'.'before'
(string) Texte à insérer avant les liens du menu.'after'
(string) Texte à insérer après les liens du menu.'link_before'
(string) Texte à insérer avant le texte des liens.'link_after'
(string) Texte à insérer après le texte des liens.'echo'
(bool) Pour afficher le menu.
Par défaut : true.'depth'
(int) Combien de niveaux de la hiérarchie sont à inclure. 0 signifie tous.
Par défaut : 0.'walker'
(object) Instance personnalisée d'un walker de classe CSS.'theme_location'
(string) Endroit du thème à utiliser. Doit être enregistré par la fonctionregister_nav_menu().'items_wrap'
(string) Comment les balises li doivent être enveloppées.
Par défaut : la balise ul avec un id et une classe css.'item_spacing'
(string) Pour préserver les espaces blancs dans le menu HTML. Accepte 'preserve' ou 'discard'.
Par défaut : 'preserve'.
Valeur par défaut : array()
Retourne
(void | string | bool) Vide si l'argument 'echo' est true, le menu HTML si 'echo' est false. Retourne false si aucuns onglets ou menus sont trouvés.
Structure de la fonction wp_nav_menu()
Définie dans le fichier wp-includes/nav-menu-template.php à la ligne 57 :
function wp_nav_menu( $args = array() ) {
static $menu_id_slugs = array();
$defaults = array(
'menu' => '',
'container' => 'div',
'container_class' => '',
'container_id' => '',
'container_aria_label' => '',
'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>',
'item_spacing' => 'preserve',
'depth' => 0,
'walker' => '',
'theme_location' => '',
);
$args = wp_parse_args( $args, $defaults );
if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
// Invalid value, fall back to default.
$args['item_spacing'] = $defaults['item_spacing'];
}
/**
* Filters the arguments used to display a navigation menu.
*
* @since 3.0.0
*
* @see wp_nav_menu()
*
* @param array $args Array of wp_nav_menu() arguments.
*/
$args = apply_filters( 'wp_nav_menu_args', $args );
$args = (object) $args;
/**
* Filters whether to short-circuit the wp_nav_menu() output.
*
* Returning a non-null value from the filter will short-circuit wp_nav_menu(),
* echoing that value if $args->echo is true, returning that value otherwise.
*
* @since 3.9.0
*
* @see wp_nav_menu()
*
* @param string|null $output Nav menu output to short-circuit with. Default null.
* @param stdClass $args An object containing wp_nav_menu() arguments.
*/
$nav_menu = apply_filters( 'pre_wp_nav_menu', null, $args );
if ( null !== $nav_menu ) {
if ( $args->echo ) {
echo $nav_menu;
return;
}
return $nav_menu;
}
// Get the nav menu based on the requested menu.
$menu = wp_get_nav_menu_object( $args->menu );
// Get the nav menu based on the theme_location.
$locations = get_nav_menu_locations();
if ( ! $menu && $args->theme_location && $locations && isset( $locations[ $args->theme_location ] ) ) {
$menu = wp_get_nav_menu_object( $locations[ $args->theme_location ] );
}
// Get the first menu that has items if we still can't find a menu.
if ( ! $menu && ! $args->theme_location ) {
$menus = wp_get_nav_menus();
foreach ( $menus as $menu_maybe ) {
$menu_items = wp_get_nav_menu_items( $menu_maybe->term_id, array( 'update_post_term_cache' => false ) );
if ( $menu_items ) {
$menu = $menu_maybe;
break;
}
}
}
if ( empty( $args->menu ) ) {
$args->menu = $menu;
}
// If the menu exists, get its items.
if ( $menu && ! is_wp_error( $menu ) && ! isset( $menu_items ) ) {
$menu_items = wp_get_nav_menu_items( $menu->term_id, array( 'update_post_term_cache' => false ) );
}
/*
* If no menu was found:
* - Fall back (if one was specified), or bail.
*
* If no menu items were found:
* - Fall back, but only if no theme location was specified.
* - Otherwise, bail.
*/
if ( ( ! $menu || is_wp_error( $menu ) || ( isset( $menu_items ) && empty( $menu_items ) && ! $args->theme_location ) )
&& isset( $args->fallback_cb ) && $args->fallback_cb && is_callable( $args->fallback_cb ) ) {
return call_user_func( $args->fallback_cb, (array) $args );
}
if ( ! $menu || is_wp_error( $menu ) ) {
return false;
}
$nav_menu = '';
$items = '';
$show_container = false;
if ( $args->container ) {
/**
* Filters the list of HTML tags that are valid for use as menu containers.
*
* @since 3.0.0
*
* @param string[] $tags The acceptable HTML tags for use as menu containers.
* Default is array containing 'div' and 'nav'.
*/
$allowed_tags = apply_filters( 'wp_nav_menu_container_allowedtags', array( 'div', 'nav' ) );
if ( is_string( $args->container ) && in_array( $args->container, $allowed_tags, true ) ) {
$show_container = true;
$class = $args->container_class ? ' class="' . esc_attr( $args->container_class ) . '"' : ' class="menu-' . $menu->slug . '-container"';
$id = $args->container_id ? ' id="' . esc_attr( $args->container_id ) . '"' : '';
$aria_label = ( 'nav' === $args->container && $args->container_aria_label ) ? ' aria-label="' . esc_attr( $args->container_aria_label ) . '"' : '';
$nav_menu .= '<' . $args->container . $id . $class . $aria_label . '>';
}
}
// Set up the $menu_item variables.
_wp_menu_item_classes_by_context( $menu_items );
$sorted_menu_items = array();
$menu_items_with_children = array();
foreach ( (array) $menu_items as $menu_item ) {
$sorted_menu_items[ $menu_item->menu_order ] = $menu_item;
if ( $menu_item->menu_item_parent ) {
$menu_items_with_children[ $menu_item->menu_item_parent ] = true;
}
}
// Add the menu-item-has-children class where applicable.
if ( $menu_items_with_children ) {
foreach ( $sorted_menu_items as &$menu_item ) {
if ( isset( $menu_items_with_children[ $menu_item->ID ] ) ) {
$menu_item->classes[] = 'menu-item-has-children';
}
}
}
unset( $menu_items, $menu_item );
/**
* Filters the sorted list of menu item objects before generating the menu's HTML.
*
* @since 3.1.0
*
* @param array $sorted_menu_items The menu items, sorted by each menu item's menu order.
* @param stdClass $args An object containing wp_nav_menu() arguments.
*/
$sorted_menu_items = apply_filters( 'wp_nav_menu_objects', $sorted_menu_items, $args );
$items .= walk_nav_menu_tree( $sorted_menu_items, $args->depth, $args );
unset( $sorted_menu_items );
// Attributes.
if ( ! empty( $args->menu_id ) ) {
$wrap_id = $args->menu_id;
} else {
$wrap_id = 'menu-' . $menu->slug;
while ( in_array( $wrap_id, $menu_id_slugs, true ) ) {
if ( preg_match( '#-(\d+)$#', $wrap_id, $matches ) ) {
$wrap_id = preg_replace( '#-(\d+)$#', '-' . ++$matches[1], $wrap_id );
} else {
$wrap_id = $wrap_id . '-1';
}
}
}
$menu_id_slugs[] = $wrap_id;
$wrap_class = $args->menu_class ? $args->menu_class : '';
/**
* Filters the HTML list content for navigation menus.
*
* @since 3.0.0
*
* @see wp_nav_menu()
*
* @param string $items The HTML list content for the menu items.
* @param stdClass $args An object containing wp_nav_menu() arguments.
*/
$items = apply_filters( 'wp_nav_menu_items', $items, $args );
/**
* Filters the HTML list content for a specific navigation menu.
*
* @since 3.0.0
*
* @see wp_nav_menu()
*
* @param string $items The HTML list content for the menu items.
* @param stdClass $args An object containing wp_nav_menu() arguments.
*/
$items = apply_filters( "wp_nav_menu_{$menu->slug}_items", $items, $args );
// Don't print any markup if there are no items at this point.
if ( empty( $items ) ) {
return false;
}
$nav_menu .= sprintf( $args->items_wrap, esc_attr( $wrap_id ), esc_attr( $wrap_class ), $items );
unset( $items );
if ( $show_container ) {
$nav_menu .= '</' . $args->container . '>';
}
/**
* Filters the HTML content for navigation menus.
*
* @since 3.0.0
*
* @see wp_nav_menu()
*
* @param string $nav_menu The HTML content for the navigation menu.
* @param stdClass $args An object containing wp_nav_menu() arguments.
*/
$nav_menu = apply_filters( 'wp_nav_menu', $nav_menu, $args );
if ( $args->echo ) {
echo $nav_menu;
} else {
return $nav_menu;
}
}
Fonctions et Hooks utilisés par wp_nav_menu()
esc_attr()Échappe les valeurs des attributs HTML.
wp_parse_args()Fusionne des arguments définis par l'utilisateur dans un tableau par défaut.
apply_filters()Appel les fonctions qui ont été attaché à un filtre (hook).
_wp_menu_item_classes_by_context()Ajoute les classes css dans le contexte actuel si applicable.
walk_nav_menu_tree()Retourne la liste HTML des onglets du menu.
wp_nav_menu_argsFiltre les arguments utilisés pour afficher un menu de navigation.
pre_wp_nav_menuCourt-circuite la fonction wp_nav_menu().
wp_nav_menu_container_allowedtagsFiltre la liste des balises HTML valides pour utiliser un conteneur du menu.
wp_nav_menu_objectsFiltre la liste triée des objets d'item du menu avant de générer le menu HTML.
wp_nav_menu_itemsFiltre le contenu de la liste HTML pour les menus de navigation.
wp_nav_menu_{$menu->slug}_itemsFiltre le contenu de la liste HTML pour un menu spécifique de navigation.
wp_nav_menuFiltre le contenu HTML des menus de navigations.
wp_get_nav_menus()Retourne tous les objets d'un menu de navigation.
wp_get_nav_menu_items()Retourne tous les items d'un menu de navigation.
wp_get_nav_menu_object()Retourne un objet d'un menu de navigation.
get_nav_menu_locations()Retourne tous les emplacements de menu de navigation enregistrés et les menus assignés.
is_wp_error()Vérifie si la variable est une erreur WordPress.
Où trouver la fonction wp_nav_menu()
dans le CMS Wordpress
Exemples
wp_nav_menu( array(
'theme_location' => is_user_logged_in() ? 'logged-in-menu' : 'logged-out-menu'
) );wp_nav_menu( array(
'menu' => 'Project Nav'
) );if( $nav['theme_location'] == 'primary' ){
wp_nav_menu( array(
'theme_location' => 'primary',
'items_wrap' => '<ul><li id="item-id">Retour</li>%3$s</ul>'
) );
}Sources
Codex Wordpress : wp_nav_menu()
Autres fonctions dans le même fichier : wp-includes/nav-menu-template.php