npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@silexlabs/eleventy-plugin-directus

v1.0.18

Published

Expose Directus collections as global data in 11ty

Downloads

18

Readme

Eleventy Plugin Directus

⚠️ Deprecated ⚠️

This project is no longer maintained and is deprecated.

If you want to use 11ty and directus together, check 11ty's official blog post. You may also be interested in Silex website builder which is a no-code tool that can generate 11ty data files with GraphQL queries to connect to directus and query exactly the data needed in the layout.

combined

Abbout this plugin

Expose Directus collections as global data in 11ty. By default the data will be available in directus.collections.*

This plugin also creates filters to manage assets URLs and translations, creates a directus.collections.all collection, and will help you make pages out of Directus collections.

Disclaimer

/!\ This plugin was used in production at Internet 2000, but it has flows explained bellow. We used it along with Silex free/libre nocode website builder which is now able to generate 11ty data files with GraphQL queries to connect to directus and query exactly the data needed in the layout. This plugin is now read-only / archived, please get in touch if you'd like to take over its development.

Following this discussion with @rijkvanzanten, lead maintainer of Directus, I need your input on how to make this plugin better, as it depends on the use cases. So please head to this discussion and let's talk use cases

Also we should make this plugin compatible with 11ty i18n/internationalization mechanism as for now it has a simple but different mechanism - see the directus_translate filter

Why this plugin?

11ty static site generator and Directus headless CMS are excellent tools, both open source and part of the JS ecosystem. They work very well together, they make a great tech stack for static and dynamic sites, and even web apps. They share a "simple is beautiful" philosophy, they are based on open standards to a great extent, and get more complex as your needs grow.

As we use 11ty+Directus a lot at internet 2000 web studio to produce eco-friendly websites, it made sense to open source this part of our code.

Also please note we use Silex website builder with 11ty+Directus as this no-code tool also has a lot in commong with Directus.

Why a plugin at all?

As you can see on this official blog post, it is easy to import Directus data into an 11ty website. With this direct approach, this is how 11ty data file which fetches Directus content.

The problem with this approach is that you will need to explicitely re-define your content structure a second time, as you already made the structure in Directus. It also requires redondant glue code for each collection you want to use in your templates.

What this plugin does is to retrieve all the data recursively from Directus and then you can use it from your templates with the "dot notation" as JSON objects. The drawback this approach - at least as it is implemented for now, is that uses a "simple" / hacky approach to just fetch everything up front, even a lot more data than you need when you have a recursive relationship, e.g. articles->related_articles->articles - see discussion here. Until now this hasn't been a problem for us as it is data that is exposed to templates and then forgotten, but feel free to discuss any better implementation details.

Use cases

Use this plugin to

  • Access directus collections from your 11ty templates, e.g. {% for collection in directus.collections.some_collection %} or {{ directus.collections.some_singleton.some_field }}
  • Easy nested collections (many to many / one to many / m2a fields), e.g. {{ directus.collections.some_singleton.some_field_many_to_many.some_field_in_nested_collection }}
  • Use translations for multi-lingual sites, e.g. {% assign translated = directus.collections.some_singleton | directus_translate: "translation_field", "fr" %}{{ translated.some_field_from_translated_collection }}
  • Render any collection with different layouts depending on the collection, e.g. render the page collection the pages.liquid and all post items in directus with posts.liquid in 11ty's _layout folder

Usage

  1. Install the plugin using npm:

    npm install @silexlabs/eleventy-plugin-directus
  2. Add the plugin to your .eleventy.js config:

    const pluginDirectus = require("@silexlabs/eleventy-plugin-directus")
    
    module.exports = (eleventyConfig) => {
      eleventyConfig.addPlugin(pluginDirectus, {
        url: 'http://localhost:8055',
      })
    }
  3. Run or build your Eleventy project and use the global directus.collections data variable to access your collections

Troubleshooting

directus_collections need to be readable, as well as the other collections you want to access in your 11ty website

For this plugin to retrieve public data, check the permissions for the public role in directus

For this plugin to retrieve private data, use the skd.authenticated option, see "Advanced options" section bellow

Advanced options

| Variable name | Desctiption | Default | | -- | -- | -- | | url | Directus server root URL | http://localhost:8055 | | name | Name of the global data key and prefix of the filters | directus | | auth | Object passed to Directus SDK's constructor as the auth option | - (optional, this is useful for custom auth implementations only) | | login | Object passed to Directus SDK's auth.login method | - (optional, this is useful to retrieve private data only) | | token | String passed to Directus SDK's auth.static method | - (optional, this is useful to retrieve private data only) | | onItem | A callback to modify each item while collections are created. Use item.collection if you need to take the collection name into account. | item => item | | filterCollection | A function which takes the collection name as input and outputs a boolean. It is applied as a filter when first getting the collections list | default: collection => collection | | allowHidden | Keep hidden collections in directus.collections.all | true | | allowSystem | Keep system collections in directus.collections.all | true | | sequencial | Should all collections and their items be fetched sequencially or in parallel | false | | recursions | How many levels of recursions do you need? This uses the fields field of requests. | 7 |

Config Examples

  eleventyConfig.addPlugin(pluginDirectus, {
    url: 'http://localhost:8055',
    name: 'directus',
    login: {
      email: '[email protected]',
      password: 'd1r3ctu5',
    },
  })

Available global data

In your templates:

  • directus.collections.${collection}
  • directus.collections.all

In JS:

const directus = await  eleventyConfig.globalData.cms()
const { pages, posts, categories } = await directus.getCollections()
const settings = await directus.getCollection('settings')
const all = await directus.getAll()
all.forEach(item => console.log(`I belong to the collection ${item.collection}`))

Filters and shortcodes

Media URL

  • directus_asseturl: get the URL from an image object coming from directus collections, e.g. {% assign url = item.image | directus_asseturl: 'This is a text displayed when an error occures (i.e. to find missing images)' %}

Translation

Use the translate filter to get the translated part of a directus collection item

| argument | description | default | example | | -- | -- | -- | -- | | translation field | The name of your directus "translations field" (see directus docs about translations fields) | Tries to find a field translations in the input item and if it fails takes the input item's collection field and append _translations to it | {% assign translated = item | directus_translate: "translations", "en" %} | | language | The language code you need | Takes the input item's lang attribute if it has one | {% assign translated = item | directus_translate: nil, "en" %} |

Returns an object with all the fields of the input, plus the fields of the object in the translations field which has lang set to the language you want

For example let's say you have a directus collection called "post" containing a list of posts. In this collection you have 2 text fields: non-translated-text and a "translation field" called translation_field. In the collection "translation_field", you have just one field called translated-text

In your layouts use the filter to find the appropriate language and merge the translation with the item itself:

{% for item in directus.collections.posts %}
  {% assign translated = item | directus_translate: "translation_field", "fr" %}
  {{ translated.non-translated-text }} This will output the value of the non translated field
  {{ translated.translated-text }} This will output the value of the non translated field  
{% endfor %}

Or in a JS data files:

directus.translate(item, "page_translations", "en")

What this filter does is find the item language (item.lang) in item[item.collection + "_translations"] and merge its content into item

Please ask in the issues if this example is not clear

Collection's items data

Each directus.collection is an array of items or an item (case of a singleton), with items look like this:

| attribute | description | | -- | -- | | collection | Name of the item's collection. | | All other attributes | The attributes you define in Directus |

Directus collections and 11ty pages

Check the documentation folder

Collections in a multi-lingual website

If you use Directus fields of type translations, you will probably need to have pages with URLs like these: /fr/page-1/, /en/page-1, /fr/page-2/, ... In that case you need an 11ty collection containing 1 item for each item of a Directus collection and for each language of your website:

[{
  "title": "bonjour",
  "lang": "fr",
}, {
  "title": "hello",
  "lang": "en",
}, {
  "title": "ca va bien",
  "lang": "fr",
}, {
  "title": "how are you",
  "lang": "en",
}]

Here is how to make that happen - let's say your language collection is named languages in directus:

  // In .eleventy.js
  eleventyConfig.addCollection('translated', async function(collectionApi) {
    const directus = await  eleventyConfig.globalData.cms()
    return directus.getAll()
      .flatMap(item => directus.collections.languages.map(({code}) => ({
        ...item,
        lang: code,
      })))
      .map(item => ({
        ...item,
        // store translated data here, e.g.
        translated: directus.translate(item, `${item.collection}_translations`),
        // or for the example above
        ...directus.translate(item, `${item.collection}_translations`),
      }))
  })

Then you can use this collection in a markdown file

---
pagination:
  data: collections.translated
  size: 1
  alias: current
permalink: /{{ current.lang }}/{{ current.some_field | slug }}/

---

<h1>{{ current.title }}</h1> <--- this will be in the current language

This title is in {{ current.lang }}

The permalink of this page includes the current language

Unit tests

npm test