For tag

{% for identifier in <expr> %}
  content
{% else %}
  content
{% end %}

{% for key, value in <map> %}
  {{ key }} = {{ value }}
{% end %}

{% for a, b, c in <arrayOfArrays> %}
  {{ a }} - {{ b }} - {{ c }}
{% end %}

The for tag evaluates the expression and, assuming it is a collection of some kind, iterates the collection, rendering its content for each iteration of the loop. Inside the loop, the given identifier (or identifiers is available for you to reference.

If you have an {% else %} block after the {% for %} block, the else block will be output if the collection is empty.

You can iterate a map and look at just the keys, or use the key, value syntax to capture both the key and the value (note: iteration of the Map happens in whatever order the Map defines, so for example HashMap will iterate in random order).

If you are iterating a collection of collections, you can use the a, b, c syntax to "expand" the inner array, for easier access.

In addition to the identifier, a special loop object is available inside the contents of for loop, with some additional information about the loop. The loop variable has the following properties:

loop.index The index of the loop we're in, 0-based.
loop.revindex The index of the loop, counting from the last element (the last element will be 0, the second last 1, and so on)
loop.first True if this is the first element in the loop (i.e. if loop.index == 0), false otherwise.
loop.last True if this is the last element in the loop (i.e. if loop.revindex == 0), false otherwise.
loop.length The total number of elements in the loop.

Examples

First, let's assume we have the follow code to render the template set up:

  CarrotEngine engine = new CarrotEngine(...);

  Bindings bindings = new MapBindings(ImmutableMap.<String, Object>builder()
      .put("users", Lists.newArrayList(
          ImmutableMap.of("id", 1234, "name", "Dean"),
          ImmutableMap.of("id", 2657, "name", "John"),
          ImmutableMap.of("id", 3464, "name", "Harry")
        )
      .put("admins", Lists.newArrayList())
      .build());

  System.out.println(engine.process("filename.html", bindings));

And the following template:

  {% for user in users %}
    <div{% if loop.first %} class="first"{% end %}>
      {{ loop.index }}: {{ user.id }} {{ user.name }}
    </div>
  {% end %}

It would output the following:

  <div class="first">
    0: 1234 Dean
  </div>
  <div>
    1: 2657 John
  </div>
  <div>
    2: 3464 Harry
  </div>

Similarly, the following template:

  {% for admin in admins %}
    {{ admin.id }} : {{ admin.name }}
  {% else %}
    You don't have any admin users.
  {% end %}

Would output the following:

You don't have any admin users.

Now, let's assume we have the follow code to render the template set up:

  CarrotEngine engine = new CarrotEngine(...);

  Bindings bindings = new MapBindings(ImmutableMap.<String, Object>builder()
      .put("user", ImmutableMap.of(
          "id", 1234,
          "firstName", "Dean",
          "lastName", "Harding"))
      .build());

  System.out.println(engine.process("filename.html", bindings));

And the following template:

  {% for key, value in user %}
    <div>
      {{ key }}: {{ value }}
    </div>
  {% end %}

It would output the following:

  <div>
    id: 1234
  </div>
  <div>
    firstName: Dean
  </div>
  <div>
    lastName: Harding
  </div>

(Though not necessarily in that order. If you want the output to be ordered, use a TreeMap, which defines the order of keys to be ascending order.)

← If tag