Jinja Batch: filter function to group sequence of items

A Quick Guide to the Jinja batch Filter

The Jinja batch filter is a powerful tool for splitting a sequence of items into smaller, fixed-size groups. Think of it like taking a long list and cutting it into equal-sized chunks. This is incredibly useful for formatting data in a structured way, especially for displaying items in a grid, table, or multi-column layout. By using batch, you can iterate over these smaller lists, making it easy to build complex layouts without complicated template logic.

---

How the batch Filter Works

The batch filter takes an iterable (like a list) and divides it into a list of sub-lists. Each sub-list will contain a specified number of items.nnThe syntax is as follows:

{{ my_list | batch(linecount, fill_with) }}

• • linecount: This is a required integer that specifies the number of items in each batch. For example, batch(3) will create sub-lists with three items each.

• • fill_with (optional): This parameter is used to pad the last batch if it doesn’t have enough items to meet the linecount. If you provide a value, the filter will fill the remaining spots with that value. If you don’t provide a fill_with value, the last batch will simply be shorter.

This filter is specifically designed to be used in a nested loop structure. The outer loop iterates through the batches (the list of sub-lists), and the inner loop iterates through the items within each batch.

---

Practical Examples

Let’s look at some examples to see how the batch filter simplifies complex layouts.

Example 1: Creating a Simple Table

A common use case for batch is to create an HTML table where each row has a fixed number of cells.nnJinja Template:

{% set items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'] %}<table>{% for row in items | batch(3) %}<tr>{% for item in row %}<td>{{ item }}</td>{% endfor %}</tr>{% endfor %}</table>

Rendered HTML:

<table><tr><td>Item 1</td><td>Item 2</td><td>Item 3</td></tr><tr><td>Item 4</td><td>Item 5</td></tr></table>

Here, the list is batched into a list of lists: [['Item 1', 'Item 2', 'Item 3'], ['Item 4', 'Item 5']]. The outer loop creates two rows (<tr>), and the inner loop fills each row with the items from its corresponding batch.

Example 2: Using the fill_with Parameter

When creating a grid or table, you often want a consistent number of columns. The fill_with parameter ensures the last row is filled to the same length as the others.

Jinja Template:

{% set items = ['Photo 1', 'Photo 2', 'Photo 3', 'Photo 4', 'Photo 5'] %}<div class="photo-gallery">{% for row in items | batch(3, '&nbsp;') %}<div class="row">{% for photo in row %}<div class="col">{{ photo }}</div>{% endfor %}</div>{% endfor %}</div>

Rendered HTML:

<div class="photo-gallery"><div class="row"><div class="col">Photo 1</div><div class="col">Photo 2</div><div class="col">Photo 3</div></div><div class="row"><div class="col">Photo 4</div><div class="col">Photo 5</div><div class="col">&nbsp;</div></div></div>

The filter takes the list and creates [['Photo 1', 'Photo 2', 'Photo 3'], ['Photo 4', 'Photo 5', ' ']]. The last row now has three columns, with the third one filled by the specified  .

---

Conclusion

The Jinja batch filter is a fundamental tool for structuring data presentation in your templates. Its ability to logically group items simplifies the creation of grids, tables, and multi-column layouts, making your code cleaner and more efficient. By understanding how to use linecount and the optional fill_with parameter, you can easily control the layout and ensure a consistent, professional-looking design.