Contenu principal

SF Meta Archives

SF Meta Archives est une extension permettant de créer des pages d’archives pour les post metas. C’est une extension à réserver aux développeurs.

Le premier point à savoir afin d’utiliser ces archives, c’est qu’elles peuvent fonctionner selon deux modes : « post type » ou « taxonomie ».

  • Mode « post type » : il y a une seule page d’archive : http://example.com/my-meta/.
  • Mode « taxonomie » : il y a une page d’archive par valeur que la meta peut prendre : http://example.com/my-meta/my-value/.

Vous aurez plusieurs fonctions à disposition :

  • register_post_meta() est une sorte de register_post_type() adapté aux post metas.
  • is_post_meta_archive() est une sorte de is_category() pour post meta.
  • get_post_meta_archive_link() retourne l’url d’une archive.
  • get_post_meta_archive_description() retourne la description d’une meta.

L’extension contient ensuite une série d’actions et de filtres qui feront le boulot désiré.

Utilisation

register_post_meta( $meta_name, $args )

Permet de déclarer la post meta pour créer la ou les pages d’archive.
Ne doit pas être utilisée avant setup_theme ou après query_vars.

$meta_name : (string) le nom de votre meta (celui utilisé dans get_post_meta() par exemple.
$args : (array) une liste de paramètres. Ces paramètres seront ensuite accessibles via la variable globale $wp_metas, ainsi qu’avec get_queried_object().

Paramètre Type Défaut Définition
post_type String|Array null Types de post. Optionnel.
query_var String null Utilisé comme variable de requête : à la place de « $meta_name = … », « $query_var = … » sera utilisé. Optionnel, fallback vers $meta_name.
query_value Bool false Passer à true pour utiliser le mode « taxonomie ».
meta_query Array array() Il s’agit du même paramètre meta_query que dans WP_Query, c’est à dire un tableau de tableaux d’arguments. Requis pour le mode « post type ».
rewrite Bool|Array true Un tableau d’arguments pour la réécriture d’URL (ou true/false) : slug, with_front, feeds, pages, ep_mask. Il s’agit des mêmes arguments que dans register_post_type(). Optionnel.
label String __('Meta Archive') Utilisé pour filtrer la fonction wp_title() pour le titre de l’archive. Optionnel, mais devrait être utilisé.
description String empty string Non utilisée par l’extension, pourra être utilisée par les développeurs de thèmes ou de plugins, elle sera stockée dans une variable globale. Optionnel.

is_post_meta_archive( $query_var = null, $query_value = null )

Indique si l’on affiche une archive de meta.

$query_var : (string) voir register_post_meta(). Optionnel.
$query_value : (string) utilisé uniquement dans le mode « taxonomie », permet de savoir si l’on affiche l’archive d’une certaine valeur de meta. Optionnel.

get_post_meta_archive_link( $query_var, $meta_value = null, $paged = 1 )

Retourne l’URL d’une archive de meta.

$query_var : (string) voir register_post_meta(). Requis.
$meta_value : (string) la valeur de la meta. Requis pour le mode « taxonomie ».
$paged : (int) page 1, page 2, etc. Optionnel.

get_post_meta_archive_description( $query_var = null, $query_value = null )

Retourne la description d’une meta.

$query_var : (string) voir register_post_meta(). Requis.
$meta_value : (string) Pour le mode « taxonomie », vous pouvez préciser une valeur : si la description contient « %s », la valeur sera utilisée. Fallback vers la valeur courante.

Exemples

1) Avoir une archive listant uniquement les articles ayant une image à la une.

01020304050607080910111213141516

add_action( 'after_setup_theme', 'register_posts_with_thumb_archive' );

function register_posts_with_thumb_archive() {
	$args = array(
		'query_var' 	=> 'with-thumb',
		'meta_query'	=> array(
			array(
				'key'		=> '_thumbnail_id',
				'compare'	=> 'EXISTS',
			),
		),
		'title'	 	=> __( 'Posts with a thumbnail' ),
		'description'	=> __( 'All my Posts with a thumbnail.' ),
	);
	register_post_meta( '_thumbnail_id', $args );
}

De plus, on peut simplifier comme ceci :

01020304050607080910

add_action( 'after_setup_theme', 'register_posts_with_thumb_archive' );

function register_posts_with_thumb_archive() {
	$args = array(
		'query_var' 	=> 'with-thumb',
		'title'	 	=> __( 'Posts with a thumbnail' ),
		'description'	=> __( 'All my Posts with a thumbnail.' ),
	);
	register_post_meta( '_thumbnail_id', $args );
}

Si key n’est pas fourni dans meta_query (ou si meta_query n’est pas fourni), register_post_meta() le fera à notre place en utilisant le paramètre $meta_name.

Pour savoir si la page affichée est notre archive :

123

if ( is_post_meta_archive( 'with-thumb' ) ) {
	// ...
}

Lien vers notre archive :

1

<a href="<?php echo get_post_meta_archive_link( 'with-thumb' ); ?>"><?php _e( 'Posts with a thumbnail' ); ?></a>

L’URL de ce lien sera http://example.com/with-thumb/ ou http://example.com?meta=with-thumb.

Description de la meta :

1

echo wpautop( get_post_meta_archive_description( 'with-thumb' ) );

2) Avoir une archive de type « taxonomie ».

Imaginons que j’ai un CPT « events » disposant d’une meta « _city » contenant un nom de ville.

010203040506070809101112131415161718

add_action( 'after_setup_theme', 'register_events_city_archive' );

function register_events_city_archive() {
	$args = array(
		'post_type' 	=> 'events',
		'query_var' 	=> 'city',
		'query_value'	=> true,
		'meta_query'	=> array(
			array(
				'key'		=> '_city',
				'value'		=> '',
				'compare'	=> '!=',
			),
		),
		'title' 	=> __( 'Events by city' ),
	);
	register_post_meta( '_city', $args );
}

Pour savoir si la page affichée est une de nos archives :

123

if ( is_post_meta_archive( 'city' ) ) {
	// ...
}

Ou pour savoir si la page affichée est celle concernant la ville de Paris :

123

if ( is_post_meta_archive( 'city', 'paris' ) ) {
	// ...
}

Lien vers l’archive concernant la ville de Paris :

1

<a href="<?php echo get_post_meta_archive_link( 'city', 'paris' ); ?>">Paris</a>

L’URL de ce lien sera http://example.com/city/paris/ ou http://example.com?city=paris.

Description de l’archive :

1

echo wpautop( get_post_meta_archive_description( 'city', 'paris' ) );

La limitation du mode « taxonomie » est relative à la nature de la meta et à la façon dont nous faisons notre meta_query.
Par exemple, nos villes pourraient être enregistrées en tant qu’ID (de CPT ?). Paris correspondrait alors à l’ID 1234 par exemple. Dès lors, l’URL vers l’archive deviendrait http://example.com/city/1234/ ou http://example.com?city=1234. Ce cas a l’avantage de ne pas prêter à confusion entre « Paris, France » et « Paris, Texas », mais a l’inconvénient de ne pas avoir une « jolie » URL.
Dans l’autre cas, la ville est enregistrée en texte, et va donc contenir des majuscules et peut-être même des espaces. J’avoue ne pas avoir encore exploré cet aspect et je m’attend à quelques problèmes, la meta_query risquant d’échouer.
Néanmoins, l’extension est assez fournie en filtres et actions pour corriger le tir en cas de besoin, à vous de les utiliser à bon escient.