« Custom Query Shortcode » est un plugin WordPress qui permet d’utiliser la fonctionnalité WP_Query sous forme de shortcode. Il vous permet également d’intégrer des requêtes dans le corps d’une page ou d’un article.

Le plugin vous permet également de personnaliser l'affichage des résultats, soit directement en code HTML, soit à l'aide de modèles personnalisés, ou encore via des « lenses », comme on appelle ce paramètre de shortcode. Si vous utilisez Twig dans votre thème, vous pouvez même passer le nom d'un modèle Twig.

Paramètres du shortcode

Ce shortcode accepte la plupart des paramètres (méthodes) de la classe WP_Query, qui sont de simples paires clé/valeur. En raison de leur complexité, il n’accepte pas les tableaux imbriqués. De plus, le plugin accepte également les paramètres suivants :

• content_limit (entier) – limite le nombre de mots à afficher ; à utiliser avec la balise {CONTENT}. Si aucune valeur n’est fournie, l’intégralité du contenu de l’article sera affichée.
• thumbnail_size (chaîne) – spécifie une taille d’image définie – à utiliser avec la balise {THUMBNAIL}
• featured – (booléen) – lorsqu’il est défini sur TRUE et qu’il existe des articles épinglés, renvoie les articles épinglés ou « en vedette ».
• shortcode - (booléen) - si la valeur est TRUE, traite tous les autres shortcodes présents dans le contenu.
• lens - (chaîne de caractères) - le nom d'un modèle permettant d'afficher vos articles.
• twig_template - (chaîne de caractères) - Spécifie un modèle Twig à utiliser pour afficher vos articles.
• posts_separator - (chaîne de caractères) - Une chaîne de caractères pour séparer les articles, par exemple « , », «
  »
• paramètres de grille - vous pouvez afficher vos articles sous forme de grille simple à l'aide des paramètres suivants :
  • cols - (entier) - nombre de colonnes de la grille
  • rows - (entier) - nombre de lignes de la grille

HTML en ligne avec des balises

Lorsque vous encadrez le sortcode avec des balises d'ouverture et de fermeture, vous pouvez utiliser du code HTML et certaines balises de sélection pour afficher vos articles. Voici les balises disponibles, qui utilisent des accolades.

• {URL} – le permalien de l’article
• {TITLE} - le titre de l’article
• {AUTHOR} - correspond à la fonction get_the_author(), affiche le nom d'affichage de l'auteur
• {AUTHOR_URL} - récupère le lien vers la page d'archives de l'auteur, utilise la fonction get_author_posts_url(),
• {DATE}: la date de rédaction de l’article en cours ; utilise la fonction get_the_date(), formatée selon le format de date et d’heure de votre site
• {EXCERPT} - utilise la fonction get_the_excerpt() pour renvoyer l'extrait de l'article
• {COMMENT_COUNT} - le nombre de commentaires associés à l’article ; utilise la fonction get_comments_number()
• {THUMBNAIL} - affiche la vignette de l'article en utilisant par défaut la taille « thumbnail » ; la taille peut être personnalisée à l'aide du paramètre « thumbnail_size »
• {CONTENT} = affiche le contenu de l'article, soit dans son intégralité, soit avec un nombre limité de mots, soit limité via le paramètre « content_limit »

Exemple de code HTML intégré :

[query posts_per_page="5" cat="3"]
{TITLE} ({COMMENT_COUNT})
[/query]

Modèles (lens)

Nous avons fourni un nombre limité de modèles simples, paramètre « lens », que vous pouvez passer via le paramètre « lens » pour afficher votre contenu.

Exemple :

[query posts_per_page="5" featured="true" lens="carousel"]

J'ai beaucoup aimé ce plugin, mais j'ai remarqué qu'il n'avait pas été mis à jour depuis un certain temps. J'ai pensé qu'il aurait besoin de plus de « lenses » ou de modèles pour être vraiment utile, j'ai donc créé une version dérivée du plugin et j'y ai apporté mes propres personnalisations.

Liste des filtres / modèles inclus

• ul - liste non ordonnée de titres d’articles liés
• ul-title-date - liste non ordonnée avec le titre lié et la date de publication
• article-excerpt - extrait d'article (titre avec lien, image mise en avant, extrait)
• article-excerpt-date - extrait d'article avec la date de publication
• cards - vignette de l'article, titre avec lien et extrait - aucun style fourni.
• Composants Bootstrap
  • accordion
  • carrousel
  • onglets - le titre de l'article devient le titre de l'onglet et l'extrait de l'article s'affiche dans le volet de contenu associé.

Vous pouvez également indiquer les noms de vos propres modèles PHP personnalisés. Le système recherchera le fichier dans votre thème actif, dans les sous-dossiers suivants :

• query-shortcode-templates/
• partials/query-shortcode-lenses/
• html/lenses/

Prise en charge des modèles Twig

Cela nécessite l'installation de Timber 2.x en tant que dépendance Composer.

Pour utiliser un modèle Twig pour l'affichage de votre requête, il suffit d'utiliser le paramètre « twig_template » à la place du paramètre « lens », et d'indiquer le chemin d'accès à votre modèle. Par défaut, Timber recherche les modèles dans le dossier « views » de votre thème actif. Vous pouvez modifier l'emplacement par défaut des modèles dans Timber.

Exemples :

[query twig_template="nom-du-modèle.twig"]
[query twig_template="dossier/nom-du-modèle.twig"]

Prise en charge des widgets hérités

Comme WordPress n'autorise pas les shortcodes dans les zones de widgets par défaut, j'ai ajouté un filtre pour permettre cette fonctionnalité.

Prise en charge de l’éditeur de blocs

Bien que vous puissiez utiliser le shortcode de requête personnalisée via le bloc « Shortcode » et qu’il fonctionne en front-end, ce plugin ne prend pas en charge la prévisualisation des résultats dans l’éditeur de blocs. Je ne prévois pas d’offrir une prise en charge complète de l’éditeur de blocs pour ce plugin.

Si vous souhaitez disposer d’un outil de requête entièrement natif utilisant l’éditeur de blocs, je vous conseille d’utiliser soit le bloc « Query Loop » intégré à WordPress, soit, pour des utilisations plus complexes, le plugin « Advanced Query Loop ».