Support loop filtering

Jinja supports pre-filtering an array to be looped over, like so: {% for i in [1, 2, 3] if i > 1 %}

Nunjucks currently doesn’t support this.

It can be emulated by nesting the {% if %} within the for loop, but this workaround doesn’t interact correctly with {% else %} blocks on for loops (which I’ve implemented in #259). If you use a non-empty list in a {% for %} loop, but after applying filtering the list is empty, the {% else %} clause should be run. Getting this behavior without filtering built into the for loop itself is clunky and verbose.

I’m willing to work up a PR for this, but I’d like to see action on #259 first, since the implementations will interact (and almost certainly conflict if done independently).

[trevorr]

To extend @AmeliaBR’s suggestion, I used bind to pass additional arguments to the filter function:

env.addGlobal('propEquals', (k, v, o) => o[k] === v);

Remember that the first argument to bind is the this value, so you need a placeholder value such as null:

{% for myItem in myList.filter(propEquals.bind(null, 'myPropName', 'myPropValue')) %}

[AmeliaBR]

For cases when your array-filtering criteria can’t be defined by a pre-existing boolean attribute on list items, myList | selectattr(attrName) won’t work.

This is the solution I came to:

To filter a list in Nunjucks, you can use the usual JavaScript Array.prototype.filter method. That requires a function that returns boolean (or at least, truthy/falsy) values when it is passed each list item.

You need to pass the function, by reference, into the JS filter function.

{% for i in myList.filter(testFunction) %}
  {# run for each item in the list that passes the test function #}
{% else %}
  {# run if no items in the list pass the test function #}
{% endfor %}

But how do you define the testFunction?

The simplest option is to define a global function in your environment configuration. So this would be the “greater than one” test from the original issue:

env.addGlobal("testFunction", function(i){ return i>1; } );
// or, in arrow notation
env.addGlobal("testFunction", (i)=>(i>1) );

In this case, the filtering test is a simple global function, that doesn’t depend on the current template context.

If your test needs data from the context, Array.prototype.filter also allows you to define a this object (which is shared by all list items) as a second parameter. So this compares if the target value on the list items equals the path value from the current template context:

{% for i in myList.filter(testFunction, path) %}
...

env.addGlobal("testFunction", function(i){ return i.target === this; } );

Alternatively, this is the approach I ended up using. It’s not as clean as the this approach, but it’s more flexible, because I don’t need to encapsulate all the relevant context into a single object:

• I define a test function in my template context as a macro. The macro resolves to an empty string or the literal string ‘false’ if I want the test to fail. (Be careful of extra whitespace here!!!) This macro does the same test as the previous example, if it is defined in the template context with the path value:

  {% macro targetMatches(item) %}{{ (item.target === path) or '' }}{% endmacro %}
  {# or #}
  {% macro targetMatches(item) %}{{ (item.target === path) }}{% endmacro %}
  

• I define the following custom Nunjucks filter function in my configuration environment. It converts the macro result into a boolean that can be used as a JavaScript filter, and uses it to filter a list:

  let filterByMacro = function(list, macro) {
    return list.filter((item)=>{
      let result = macro(item);
      return result && result.val && (result.val !== 'false');
        // result of a macro is a SafeString object with its text value in the .val property
    });
  

• I then filter (in the JavaScript sense) the list, by passing it to my custom filter (in the Nunjucks sense), referring to my custom macro by name as a parameter:

  {%- set filtered = myList | filterByMacro(targetMatches) %}
  {% for i in filtered | sort %}
  ...
  {# or skip the intermediary variable: #}
  {% for i in myList | filterByMacro(targetMatches) | sort %}
  ...
  

It’s a little messy & difficult to follow, but it gets the job done.

Of course, a nicer built-in way to do any of this would be very helpful.

PS, For anyone else using Metalsmith, you can set custom global functions or filter functions using the engineOptions parameter to metalsmith-layouts or metalsmith-in-place. The details for that options object are in the Readme for jstransformers-nunjucks