Les collections dans Eleventy

Source : Working with Collections de Philip Borenstein

Dans Eleventy les collections permettent de grouper des articles selon divers critères. Une collection pourrait désigner une série d’articles. Un autre collection pourrait regrouper les articles à propos de livres. Une troisième collection pourrait rassembler tous les contenus d’un même répertoire.

Eleventy vous permet de créer des collections de deux manières :

• implicitement, à l’aide de tags dans le front matter
• explicitement, avec la fonction addCollection()

Les collections à base de tags

Toutes les pages qui partagent un même tag appartiennent à la même collection. Un modèle avec le front matter suivant va générer des pages dans les collections books et reviews.

---
title: Finding Oz
category: Culture
tags:
- books
- reviews
---
. . .

Dans un modèle, on accède aux collections par leur nom, en tant que propriété de l’object global collections.

<p>
  Le titre de cette page est :
  {{ collections.books[0].data.title }}
</p>

On utilise généralement les collections dans des boucles afin d’itérer sur chaque élément de la collection.

{% for post in collections.books %}
  {{ post.data.title }}
  {{ post.url }}
  {{ post.data.category }}
  {{ post.data.tags }}
  {{ post.date }}
{% endfor %}

L’objet collections lui, ressemble à ça :

{
  "all": [...],
  "nav": [...],
  "books": [
    {
      "inputPath": "./src/articles/finding-oz.md",
      "outputPath": "_site/articles/finding-oz/index.html",
      "fileSlug": "finding-oz",
      "data": {...},
      "date": "2009-08-07T13:52:12.000Z",
      "url": "/articles/finding-oz/",
      "templateContent": "<p>As with most books ... much about The Wizard of Oz</li>\n</ul>\n",
      "template": {...}
    },
    ...
  ],
  "programming": [...],
}

Chaque propriété est un tableau d’objets d'éléments de collection (également appelés objets modèle dans la documentation).

La collection spéciale all représente un tableau de tous les objets page générés par Eleventy.

getTaggedCollectionsData() est la fonction qui transforme des tags en collections.

146async getTaggedCollectionsData() {
147  let collections = {};
148  collections.all = this.createTemplateMapCopy(
149    this.collection.getAllSorted()
150  );
151  debug(`Collection: collections.all size: ${collections.all.length}`);
152
153  let tags = this.getAllTags();
154  for (let tag of tags) {
155    collections[tag] = this.createTemplateMapCopy(
156      this.collection.getFilteredByTag(tag)
157    );
158    debug(`Collection: collections.${tag} size: ${collections[tag].length}`);
159  }
160  return collections;
161}

getTaggedCollectionsData() est appelée dans TemplateMap.cache() qui est l’endroit ou Eleventy génère les collections.

Les collections sur mesure

Outre les collections créées à partir de tags, vous pouvez utiliser la fonction addCollection() dans votre fichier de configuration .eleventy.js pour créer vos propres collections.

Par exemple, voici comment créer une collection nommée articles constituée de pages générées à partir de modèles présents dans le dossier src/articles/ :

eleventyConfig.addCollection("articles",
  collection => collection
    .getAllSorted()
    .filter(item => item.url
                 && ! item.inputPath.includes('index.njk')
                 && item.inputPath.startsWith('./src/articles/')))

La fonction addCollection() prend deux paramètres¹ :

• le nom de la collection (une chaîne de caractères)
• une fonction qui prend une collection en paramètre.

Vous pourriez penser que le paramètre collection est un tableau d’objets de modèle comme l’objet collections basé sur les tags. Ce paramètre est en fait une instance d’une TemplateCollection, qui dérive de Sortable, et ressemble à ceci :

{
  "items": [
    { ... },
    . . .
    { ... }
  ],
  "sortFunctionStringMap": { ... },
  "sortAscending": true,
  "sortNumeric": false
}

La propriété items est un tableau de tous les objets de modèle. C’est la même chose que collections.all. Vous ne voulez pas accéder aux éléments directement en écrivant : collection.item[n]. Utilisez plutôt les méthodes suivantes pour accéder aux éléments.

Les éléments sont presque les mêmes que ceux des collections basées sur des tags, à la différence près que dans les collections basées sur des tags, les éléments ont une propriété templateContent. Dans les collections créées avec la fonction addCollection(), les éléments ont une propriété _pages. Je ne saurais dire pourquoi.

Vous pouvez utiliser addCollection() pour créer des collections de pages. Depuis Eleventy 0.5.3, vous pouvez l’utiliser pour créer des collections ou des objets de votre choix.

Par exemple, voici comment vous créeriez une collection constituée d’un tableau de toutes les catégories :

module.exports = function(collection) {
  let catSet = new Set()

  collection.getAllSorted().forEach(item =>
        typeof item.data.category === "string"
    &&  catSet.add(item.data.category))

  return [...catSet]
};

getUserConfigCollectionsData() est la fonction qui appelle ce qui est retourné par la fonction addCollection().

async getUserConfigCollectionsData() {
  let collections = {};
  let configCollections =
    this.configCollections || eleventyConfig.getCollections();
  for (let name in configCollections) {
    let ret = configCollections[name](this.collection);

    // work with arrays and strings returned from UserConfig.addCollection
    if (
      Array.isArray(ret) &&
      ret.length &&
      ret[0].inputPath &&
      ret[0].outputPath
    ) {
      collections[name] = this.createTemplateMapCopy(ret);
    } else {
      collections[name] = ret;
    }

    debug(
      `Collection: collections.${name} size: ${collections[name].length}`
    );
  }
  return collections;
}

getUserConfigCollectionsData() est appelé dans TemplateMap.cache() qui est l’endroit où Eleventy construit les collections.