Implementing Categories

OK, so.

This is all throat-clearing to get to where we want to go: To create a page-level property categories that works in a way similar to tags.

It may turn out that the easier way to do this is to just use the existing tag mechanism. It’s just that the idea of having to write something like this is kind of gross:

---
date: 10/30/2018
title: Loomings
tags:
  - classics
  - contrived
  - _cat_examples
---

It should look like this:

---
date: 10/30/2018
title: Loomings
category:
  - examples
tags:
  - classics
  - contrived
---

Effing tags: how do they work? #

Eleventy treats the tags page property special. For every tag name, there’s a corresponding array of all the templates with that tag.^[1]

When you want to create a new collection that’s not a tag, you can use addCollection() in your .eleventy.js configuration file.

addCollection() takes two arguments:

• the name of the collection (a string)
• a function that takes a collection as an argument.

  eleventyConfig.addCollection("articles", function(collection) {
    return collection.getAllSorted().filter(function(item) {
      return item.url && item.inputPath.startsWith('./src/articles/');
    });
  });

So, what’s in this collection parameter?

We’re interested in the items array. This table shows what an item looks like.^[2]

Let’s put links in these tables.

Eff that. Use the VS Code debugger #

Because what we really want to do is: to create a page-level property categories that works in a way similar to tags.

How do the tagged items end up in the collections? Haven’t we done this already? Yes we have.

The place where that happens looks like this:^[3]

async getUserConfigCollectionsData() {
  let collections = {};
  let configCollections =
    this.configCollections || eleventyConfig.getCollections();
  for (let name in configCollections) {
    collections[name] = this.createTemplateMapCopy(
      configCollections[name](this.collection)
    );
    debug(
      `Collection: collections.${name} size: ${collections[name].length}`
    );
  }
  return collections;
}

This is a typical way of creating a collection.

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

We’re creating a collection made up of pages that were rendered from templates in the ./src/articles/ directory.^[4]

And this collection is made up of pages that were rendered from templates that have a fun-examples tag.

  eleventyConfig.addCollection("fun-examples", collection =>
    collection.getFilteredByTag("fun-examples"));

Let’s look at how getFilteredByTag() is implemented:^[5]

getFilteredByTag(tagName) {
  return this.getAllSorted()
             .filter(item =>
                item.data.tags.some(tag => tag === tagName))
}

This is how the the individual collections get into to the collections property:

async getTaggedCollectionsData() {
  let collections = {};
  collections.all = this.createTemplateMapCopy(
    this.collection.getAllSorted()
  );
  debug(`Collection: collections.all size: ${collections.all.length}`);

  let tags = this.getAllTags();
  for (let tag of tags) {
    collections[tag] = this.createTemplateMapCopy(
      this.collection.getFilteredByTag(tag)
    );
    debug(`Collection: collections.${tag} size: ${collections[tag].length}`);
  }
  return collections;
}

Where does getTaggedCollectionsData get called? In TemplateMap.cache(). Hmmm. That’s not terribly useful. Is that where the magic happens?

I’m getting ahead of myself.

• Can an article have more than one category, or only one?
• What would it mean for there to be more than one category?
• OK, only one category.

What is a category?

It’s like a newspaper section. The idea is to build silos for things that shouldn’t go together. Or that don’t necessarily go together.

What are the categories then?

---
date: 10/30/2018
title: Loomings
category: Tech
tags:
  - tools
  - git
  - eleventy
---

What’s the default category?

• stuff
• misc
• things
• uncategorized

Maybe a special category name that never gets rendered. It doesn’t really matter.

OK, so what we’re going to do is to make our getCatList function do several things:

• create the categories collection^[6]
• create a collection with all of the category names

Have we talked about how we’re actually going going to use these categories? Something like this:

{{ collections.categories.Culture }}

Now what? #

Let’s see if this works. Let’s try to make category pages analogous to the tag pages.

Where to start? The tag list in tags-list.njk looks like this:

---
permalink: /tags/
---
<h1>Tags</h1>

{% for tag in collections.tagList | sort %}
  {% set tagUrl %}/tags/{{ tag }}/{% endset %}
  <a href="{{ tagUrl | url }}" class="tag">{{ tag }}</a>
{% endfor %}

Let’s make a copy of it called category-list.njk. And copy tags.njk to categories.njk.

OK, this is weird.

This is how I create the categories. There’s a new categories property in data.collections. Then for each category, the idea is to create an array element / object property. I want to be able to write collections.categories.Culture.

  sortedCollection.forEach(function(item) {
    if (! ("categories" in item.data.collections)) {
      // no categories collection? make one
      item.data.collections.categories = {}
    }

    if (typeof item.data.category === "string") {
      catSet.add(item.data.category)
      if (!Array.isArray(item.data.collections.categories[item.data.category])) {
        item.data.collections.categories[item.data.category] = []
      }

      item.data.collections.categories[item.data.category].push(item)
    }
  });

So I’ll get something like this:

collections: {
  all: [ items ],
  categories: {
    Culture: [ items ],
    Life: [ items ],
    Thinking: [ items ]
  }
}

I was getting an error:

TypeError: collections[collectionName] is not iterable

This turned out to be a bug, where Eleventy was expecting that every property was some sort of array. This gets fixed in version 0.6.0..