Block : category grid

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. Vous pouvez mettre une simple valeur ou utiliser des placeholder suivants : {POST[variable_name]}, {GET[variable_name]}, {SESS[variable_name]}, {COOK[variable_name]}, {META[variable_name]}, {DATE[date_format]} pour appeler directement une valeur issue respectivement des supervariables $_POST, $_GET, $_SESSION, $_COOKIE, une valeur meta associée au post en cours (valeur acf simple ou meta wp natif), ou enfin la date en cours (en indiquant un formattegre de date, comme par exemple  : Y-m-d).
  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, … »