Block : category grid

Ce block très généraliste permet de créer une requête d’articles d’une ou plusieurs catégories, et d’en afficher le résultat sous forme d’une liste d’items personnalisables. Cette liste peut être paginée, posséder des fonctions de filtres, ou s’afficher sous la forme d’une grille classique ou de type « masonry ».

Contenu

  • Title (texte – facultatif) : le titre global du block, occupant toute sa largeur
  • Header (contenu – facultatif) : l’en-tête du block, occupant toute sa largeur
  • Template type (choix) : permet de sélectionner la façon dont seront construits les éléments de la liste
    1 – Simple type : à partir d’un code html arbitraire. Avec ce mode, il est possible d’attribuer une ou plusieurs classes spécifiquement au premier item de la liste (la classe embarquée « fullwidth » permet de le mettre en pleine largeur)
    2 – Import file subtemplate (url) : à partir d’un modèle statique sous forme d’un fichier php. Ce fichier doit respecter deux conditions : se trouver dans le répertoire du thème localfiles/subtemplates/ et renvoyer le contenu sous forme d’une variable
    3 – Slide overlay type : à partir du component slide overlay, se référer à sa documentation pour plus d’informations
    4 – Flip-flop card type : à partir du component flip-flop card, se référer à sa documentation pour plus d’informations
  • Footer (text – facultatif) : le pied de page du block; occupant toute sa largeur

Quelque soit le type d’affichage séléctionné pour les items (template type), vous pouvez utiliser des alias pour afficher des données dynamiques dans les champs le permettant :

  • {TITLE} : le titre de l’article
  • {THUMBNAIL} : la vignette (« image mise en avant ») de l’article
  • {EXCERPT} : l’extrait de l’artticle
  • {CONTENT} : le contenu de l’article
  • {DATE} : la date de l’article
  • {SHORTDATE} : la date courte de l’article (jour – mois)
  • {URL} : l’adresse de l’article
  • {FIELD/acf_field_name/FIELD} : la valeur d’un champ personnalisé ACF. Dans le cas d’une image ou d’un fichier, c’est l’url qui est retournée,
  • {FIELD/excerpt[acf_field_name]/FIELD} : le résumé d’un champ personnalisé ACF., si ce dernier est du texte ou du contenu
  • {RAND/LIST[elem1;elem2;elem3…]/RAND} : une valeur choisie au hasard das la liste définie elem1;elem2;elem3; etc
  • {RAND/BETWEEN[value1;value2]/RAND} : une valeur numérique choisie au hasard entre les deux nombres value1 et value2
  • {ALTERN/value1;value2;value3/ALTERN} : une alternance de valeurs suivant la l’ordre value1 – value2 – value3 – value1 – value2 – value3 – value 1 – etc
  • {FIELD/label[acf_field_name]/FIELD} : l’intitulé correspondant à la valeur retournée, utile pour les champs à choix multiples
  • {FIELD/slug[acf_field_name]/FIELD} : la chaine compatible avec les normes CSS de la valeur (exemple : « Test référence » deviendra « Test_rfrence »)
  • {FIELD/interval[acf_field_name1/acf_field_name2]/FIELD} : une chaine construite à partir d’une ou deux dates (« Le … » si une seule date est renseignée ou « Du … au … » si deux dates sont renseignées)
  • {FIELD/nosanitize[acf_field_name]/FIELD} : une chaine brute, ne passant pas par les fonction de sanitization de code

 

 

Réglages

Les réglages de ce block se répartissent en plusieurs sections :

  • query : les critères de construction de la requête servant à lister les articles. Ils suivent la logique de la fonction wp_query de WordPress (en savoir plus ici)
  • if no results return (choix) : comportement du block en cas de résultat nul de la requête, « Hide block » pour masquer le block, ou « Show message » pour afficher un message générique à la place du block
  • classes empty result message (texte) : class(es) css à appliquer au message
  • empty result message (texte) : message générique affiché à la place du block en cas de résultat nul de la requête
  • display mode : le mode d’affichage de la liste
  • activate pagination : l’activation de la pagination et les options relatives
  • filter items : l’activation des filtres sur les items de la liste et les options relatives
  • event items : transforme le traitement des items en événements basés sur des dates

 

1 – QUERY

Vous pouvez construire un requête avancée en utilisant ces différents réglages. Les requêtes sont de deux types, régis par le paramètre « query type » (choix) :

  • selection : une sélection manuelle des publications à afficher. Dans ce cas, le champ « selection » (choix) vous permet de définir cette sélection
  • category : une sélection classique par catégorie(s). Ici, vous pouvez définir :
    – post type (choix): vous pouvez choisir ici le type de publication à lister. Par défaut : articles. Vous pourrez ainsi sélectionner des types personnalisés si vous en définissez.
    – category(s) (choix) : sélectionner ici une ou plusieurs catégories
    – logic of select (choix AND/OR/EXCLUSION) : si plusieurs catégories sont sélectionnées, vous pouvez ici ajuster la logique de sélection (AND : cat1 AND cat2, OR : cat1 OR cat2, EXCLUSION : NOT IN cat1)

Les autres paramètres sont communs aux deux types de requête.

  • order (choix) : choix du critère à retenir pour définir l’ordre de la liste
  • order direction (choix) : choix du sens du tri de la liste
  • limit : le nombre d’item à sélectionner. La valeur -1 (défaut) indique de tout sélectionner.
  • exclude current post (choix) : permet d’éliminer l’item courant de la liste

Les critères suivant permettent d’affiner la sélection en imposant des critères basés sur des champs personnalisés.

  • meta relation (choix) : définit la logique de traitement des différents critères qui seront définis dans les champs suivants
  • meta object : vous pouvez définir jusqu’à 3 critères de selection. Pour chacun, il faut préciser
    key : l’identifiant du champ personnalisé
    value : sa valeur
    compare : son opérateur de comparaison
    type : le type de valeur

 

2 – DISPLAY MODE

Choisissez ici la façon dont doit apparaitre la liste des items sélectionnés via la requête.

  • bootstrap grid : une grille d’item classique, chaque item d’une ligne ayant la même hauteur
  • masonry grid : une grille plus complexe, ou les items peuvent avoir une largeur et une hauteur indépendante des autres
  • carousel : présenter la liste sous forme d’une slider

Pour chacun des types d’affichage, vous retrouverez une série de réglages.

2.1  – Bootstrap grid

  • items per lines : définit le nombre d’items par ligne
  • items per lines (md) : définit le nombre d’items par lignes sur des résolution intermédiaires
  • items per lines (sm) : définit le nombre d’items par lignes sur de petites résolution (mobiles)

2.2 – Masonry grid

Ce type de grille est plus complexe, et est basé sur la bibliothèque js masonry.desandro.com. Son élaboration est un peu plus complexe.

  • activate image loaded (choix) : à activer si votre grille comporte des images. cela enclenche un javascript qui permet de décaler le chargement des images et permettra à votre grille de se construire sans décalages
  • sizer width (nombre ) : définit l’unité de base des items dans la grille. A ajuster selon le résultat, pour occuper toute la largeur du container. Une valeur faible permettra de jouer plus finement sur ces calculs automatiques
  • sizer width unit (choix) : définit l’unité, en px ou %, de cette unité de base
  • gutter (nombre – px) : permet de définir l’unité d’espacement des items
  • animated (choix) : lance une animation simple à la construction de la grille
  • percent position (choix) : calcule la largeur des items non pas en valeurs absolue (px) mais en valeurs relatives (%)
  • horizontal order (choix) : définit l’ordre de placement des items sur un plan horizontal ou vertical

Ce type de grille nécessite que vous définissiez un champ ACF associé à vos items et définissant une largeur, variable mais prédéfinie. Par exemple, vous définissez un champ ACF « largeur_item » ayant pour valeurs possibles w25, w50, w75 et w100, dans le but de construire la grille avec des blocs de 25%, 50%, 75% ou 100% de sa largeur.  Dans ce cas veillez à bien régler « percent_position » sur « yes ».

  • ACF field definig width (slug) : l’identifiant du champ ACF permettant de récupérer l’indication de largeur (« largeur_item » dans notre exemple)
  • elements width lists (groupe répétable) : chaque groupe est défini par un nom de classe css (correspondant à chacune des valeurs du champs ACF indiqué précédemment) et sa largeur (width), l’unité choisir dépendant de la valeur du paramètre « percent_position ». Ici, il faudra créer 4 groupes : w25 à 25, w50 à 50, w75 à 75 et w100 à 100.

2.3 – Carousel 

Il s’agit ici de définir un slider faisant délier vos items. Chaque slide est construit sur le modèle définit dans « element template » ou « import file subtemplate », de l’onglet content (voir plus haut).

Les options sont identiques à celle du block slider.

 

3 – PAGINATION

Si vous avez activé la pagination, vous verrez apparaitre les options liées.

  • position (choix) : permet de définir ou placer le menu de pagination : en haut, en bas ou les deux
  • item per pages (nombre) : fixe le nombre d’items à afficher par pages
  • class of container pagination holder (string) : permet d’attribuer une classe spécifique au container du menu de pagination, utile pour affiner ses styles css par exemple
  • label previous page et label next page (string) : permettent d’indiquer les mentions figurant dans les boutons page précédente et page suivante

Notes :

1 – L’apparence du menu de pagination est configurable dans custom styles editor > plugin styles > pagination section.
2 – La pagination est opérante pour les modes d’affichage bootstrap grid » et « masonry grid » seulement

 

4 – FILTRES

Cette fonctionnalité permet de disposer automatiquement de sélecteurs permettant de filtrer les items selon un ou plusieurs critères. Les options associées apparaissent si vous avez choisi « yes » dans le critère « filter items ? ».

  • text when nothing found (string) : la phrase apparaissant lorsque les filtres ne font remonter aucun résultat
  • logic (choix AND ou OR) : si plusieurs filtres sont utilisés, permet de définir l’opérateur logique les liant
  • search filter (choix) : active ou non un champ de recherche limité aux items de la grille
  • reset button (choix) : active ou non un bouton permettant de réinitialiser les filtres et la grille

Les filtres eux mêmes sont à définir dans le groupe répétable « filters ». Chaque filtre se compose des paramètres suivants :

  • title (string) : l’intitulé du filtre
  • source (choix) : la source des données liées au filtre, soit un champ ACF, soit des catégories WordPress
  • ACF field slug (string) : le nom technique (slug) du champ ACF associé
  • type (choix) : le type de filtre, soit liste déroulante (dropdown), soit liste de boutons (button), soit, pour les champs de type « vrai/faux », un bouton on/off (switcher)
  • active value (string) : uniquement pour le type bouton on/off, y préciser la valeur définissant l’état « on »

5 – EVENEMENTS

Ce groupe d’options s’affiche si le paramètre Event items est validé. Les objets de la grilles serons considérés comme des événements, ce qui aura pour incidence :
– de modifier la requête originale pour que les critères des metas soient en mode relationnel « AND »,
– de changer l’ordre des résultats, pour un tri par date de début des événements classés en ordre descendant (y compris vi vous aviez défini plus haut d’autres critères d’ordre)
– les événements passés se verront affecter une classe « past_event », ceux présents ou à venir une classe « active_event »
– vous pourrez utiliser le placeholder {{eventdate}} pour afficher l’indicateur de date (« Le XXX » ou « Du XX au XXX » selon les cas) dans votre modèle (voir Contenu plus haut).

  • Mode (choix) : définit le séquençage d’affichage des événements, soit tous les événements, soit seulement les événements passés, soit seulement les événements présents et à venir,
  • Start date slug et End date slug (identifiants) : les identifiants des champs ACF correspondant respectivement à la date de début et à la date de fin des événements. Seul le premier est strictement obligatoire pour que le système fonctionne. Ces champs doivent retourner en base de donnée un valeur type Y-m-d,
  • Desactivate past event link (choix) : dans le cas où vous avez utilisé une classique « linkable » dans votre modèle, si cette option est activée, cette classe sera désactivée pour les événements passés
  • Past events hide items (texte) : vous pouvez préciser ici les éléments css à masquer dans les événements passés, ces éléments doivent être séparés par une virgule (exemple : « .item1, .item2, … »