Explication sur « Range » et « with » avec le framework Hugo

Hugo utilise un langage de Template pour rendre les pages de son site web. Dans un moteur de template web, les boucles (loop) sont indispensables pour lister des contenus afin d’obtenir la liste des catégories des derniers articles ou les pages d’une section du site. Avec le framework Hugo, il existe plusieurs types de boucles et plusieurs façons de les utiliser.

La boucle range

La boucle range est utilisé pour parcourir une liste d’informations à travers des variables fournie par le template suivant le contexte ( en fonction de l’URL sur laquelle nous nous trouvons)

Fonctionnement

Par exemple, en visitant l’URL « monsite.fr/posts/ » le Template correspondant à cette URL nous fournit une variable .Pages contenant la liste de toutes les pages de type « posts ». On pourrait afficher la liste de ces pages de cette manière :

{{ range .Pages }}   
 {{ .Title }}   
{{ end }}  

Cibler un contenu précis

Il est possible de récupérer uniquement les pages parcourues d’un dossier précis dans le dossier « content/ ». En réalité, on parle de Section avec Hugo.

Exemple d’utilisation :

{{ range where .Site.Pages "Section" "articles" }}  
{{ .Params.Title }}  
{{ end }}  

Dans cet exemple nous filtrerons notre collection en parcourant l’ensemble des pages du site (.Site.Pages) mais en ne gardant que les pages présentes dans le dossier content/articles/

Il est possible d’utiliser un raccourci afin d’obtenir une syntaxe simplifiée :

{{ range .Section "articles" }}  
{{ .Params.Title }}  
{{ end }}  

Limiter le nombre de pages récupérées

Dans le cas d’une pagination, ou simplement éviter d’avoir une liste de pages trop longue, il est possible de limiter le résultat de notre requête. Voici un exemple simple pour effectuer une limite sur le nombre de résultats :

{{ range first 8 .Site.Pages }}
  {{ .Title }}
{{ end }}

Cette boucle liste les huit premières pages trouvées à l’aide de la boucle ranges en parcourant toutes les pages du site.

Il est possible de combiner la limite de résultat avec un ciblage de type de contenu précis. Voici un autre exemple plus avancé :

{{ range first 8 (where .Site.Pages "Type" "planetes" )}}
  {{ .Title }}
{{ end }}

Cette boucle retournera en résultat les huit premières pages de type « planetes » (« type:planetes » dans la zone des métadonnées de l’article parcouru) du site web.

La fonction with

Si elle ressemble au premier abord à la boucle, range. Cette fonction est différente. with regroupe deux utilisations possibles.

1. Simplifier le contexte

with est souvent utilisé afin de simplifier un contexte pour des variables. par exemple :

{{ with .Person }}  
   {{ .Name }}  
   {{ .Age }}  
{{ end }}  

Dans cette situation with permet de ne par réutiliser le contexte .Person pour exploiter l’âge et le nom (ex. : .Person.Name et .Person.Age).

with semble peu pertinent dans cette situation, mais il arrive que les variables soit vraiment très longues et difficiles à intégrer entre des balises HTML. Dans ce cas with permet de simplifier et faciliter l’écriture et la lecture du template.

2. Extraire des données d’un fichier

Dans un autre cas d’utilisation with combiné à la fonction GetPage permet d’extraire les données d’un fichier précis.

Dans cet exemple on peut remarquer que si le chemin définit est relatif, with récupérera le post en question. Dans le cas ou le chemin serait absolue, with récupérera le fichier _index.md.

{{/* dans la section blog */}}

{{ with site.GetPage "post-1.md" }}  
  {{ .Title }} {{/* affiche le titre de la page content/blog/post-1.md */}}  
{{ end }}

{{ with site.GetPage "/events" }}  
  {{ .Title }} {{/* affiche le titre de la page content/events/_index.md */}}  
{{ end }}  

À la différence ou range combiné à la fonction « getPage », aurait été utilisé pour récupérer toutes les pages d’un dossier ou d’une catégorie.