Add a new `map` template tag that formats a list of items and returns them in a new list

[meesterguyman]

Code of Conduct

• I agree to follow Django's Code of Conduct

Feature Description

In python, we can use the map function to perform an operation on each member of a list (or list-like object) and then return the results in a new list. For example, assuming a queryset of users:

format_func = lambda user: f'<div><b>{{ user.name }}</b> from {{ user.city }} ({{ user.age }}</div>'
formatted_users_list = map(format_func, users)

It would be helpful to be able to do this directly from within a template, so that, given a users queryset, we could derive formatted_users_list, which could then be passed on to another template tag or fed into another template for further processing. I would propose the following format:

{% map user in users as formatted_users_list %}
  <div><b>{{ user.name }}</b> from {{ user.city }} ({{ user.age }}</div>
{% endmap %}

In both of the above cases, formatted_users_list now holds formatted HTML for each user record. This list could then be passed to another template as follows:

{% include 'some/fixed/template.html' only_a_list_no_strings=formatted_users_list %}

Problem

If I have a list-like object, each of whose members need to be formatted in a particular way, and I want to display results directly on the page, a simple for loop will do the trick. If I want to capture the output as a string, a "simple_block_tag" will work. But if I want to format members and then pass results as a list to another template that requires a list rather than a string, then I need a template tag that operates on an iterable in template context and then injects the resulting list back into template context in a manner that is visible to subsequent tags / includes. At present, there is no straightforward way to do this.

Request or proposal

proposal

Additional Details

I've already built it. See below.

Implementation Suggestions

The following code is tested and working.

class MapNode(template.Node):
    def __init__(self, item_var, items_iterable, new_list_name, nodelist):
        self.item_var = item_var
        self.items_iterable = items_iterable
        self.new_list_name = new_list_name
        self.nodelist = nodelist

    def render(self, context):
        new_list = []
        for item in self.items_iterable.resolve(context, ignore_failures=True):
            context[self.item_var] = item
            new_list.append(self.nodelist.render(context))
        context[self.new_list_name] = new_list
        return ''

@register.tag('map')
def do_map(parser, token):
    """
    This tag is meant to emulate the python ``map`` function, accepting a list of X items, rendering them
    one at a time using the template fragment within the map block, and saving the result into a template
    variable, which can then be passed on to another template tag or template.

    For example, suppose we have a list of users and want to wrap each item in the list in HTML. We might
    do this in python as follows before passing it into template context::

        wrapped_users = map(lambda user: f"<div><b>{user.name}</b> from {user.city} ({user.age})</div>", users)

    Or we could do it directly inside a Django template as follows::

        {% map user in users as wrapped_users %}
            <div><b>{{ user.name }}</b> from {{ user.city }} ({{ user.age }})</div>
        {% endmap %}

    Either way, ``wrapped_users`` will now contain one HTML formatted item for each user in ``users``.

    The syntax here is similar to that of a for loop, but unlike the for loop, which renders output in place,
    an "as" clause is required here to indicate the name of the context variable in which the resulting list
    should be stored. This variable will then be injected into context for later use.
    """
    error = False
    try:
        _, item_var, in_kw, items_iterable, as_kw, new_list_name = token.split_contents()
        if in_kw != 'in' or as_kw != 'as':
            error = True
    except:
        error = True
    if error:
        raise TemplateSyntaxError("'map' tags take the form {%% map ITEM_VAR in ITEMS_ITERABLE"
                                  " as NEW_LIST_NAME %%}; you entered {%% %s %%}" % token.contents)
    nodelist = parser.parse(('endmap',))
    parser.delete_first_token()
    items_iterable = parser.compile_filter(items_iterable)
    return MapNode(item_var, items_iterable, new_list_name, nodelist)

[github-actions]

Thank you meesterguyman for sharing your idea! We have a lot of them so please be patient. You can see the current queue here.

Community instructions

For commenters, please use the emoji reactions on the issue to express support, and/or concern easily. Please use the comments to ask questions or contribute knowledge about the idea. It is unhelpful to post comments of "I'd love this" or "What's the state of this?"

Reaction Guide

• 👍 This is something I would use
• 👎 This is something that would cause problems for me or Django
• 😕 I’m indifferent to this
• 🎉 This is an easy win

[LilyFirefly]

I've put the Third Party Package label on this because this can be created as a third-party package right now, rather than needing to wait for Django 6.2 at the earliest. If there's enough desire for this, we can reconsider adding it to core.

[codingjoe]

I have rather strong concerns about the naming. map is a common directive in almost all programming languages and used to apply each item in an iterable to a function.

IMHO: Misusing the name in a different context will cause more confusion than good whilst I still find the usecase very slim and solveable with an inclusion tag, see also: #176 (comment)

[meesterguyman]

@codingjoe I'm not necessarily tied to the name, though, if you think of the content of the tag as a function, it does, in my view, mirror the functionality of python's map function.

As for using an inclusion tag, the problem with that is that inclusion tags are tied to a specific template, such that for every new template I want to render, I have to create a new inclusion tag, resulting in lots of case-specific inclusion tags. With the tag I've suggested in place, you have a general solution that will work with any template. Personally, I prefer to keep custom template tags to a minimum, especially when they going to be tied to a particular rendering.

[codingjoe]

@meesterguyman OK, I see how you ended up with the name. I still find it a stretch.

Anyhow, if you simply want to render a the object with a nice template, please consider implementing User.__html__(). In Django any object can be HTML safe and define its own __html__() function which, if present, will called when value is rendered.

In your case:

class User:
    def __html__(self):
        return format_html("<div><b>{}</b> from {} ({}</div>", self.name, self.city, self.age)

This will give you per object templates. We use this for media assets interally too.

[jacobtylerwalls]

@codingjoe Do we document that __html__() usage?

[meesterguyman]

@codingjoe I provided the users scenario just as an example. My actual use case is what I describe in the previous idea I put up for the for tag, which you referenced in your comment above.

In short, I'm attempting to generate standardized columns for responsive emails. The most obvious way to do this is to create a columns.html template that accepts a list of items and formats them the same way, regardless of content. We have several sections with different types of content, requiring different widths and layouts, and this template needs to handle all of them. You can get a sense of what I'm after from the template below:

{% load my_tags %}
{% comment %}
This template takes a list of "column_trs" (table rows to be inserted within the TBODY tag of the containing column)
and formats each to be displayed in its own separate column. "column_width" determines the width of each column, and
"columns_per_row" the maximum number of columns per row on desktop. Alternatively, "row_width" (the maximum width of
all columns in a row should occupy) may be provided, and "column_width" will be calculated.
{% endcomment %}
{% firstof column_width row_width|div:columns_per_row as column_width %}
<div class="columns">
  <!--[if true]><table><tbody><tr><td style="width:{{ column_width }}px"><![endif]-->
  {% for tr in column_trs %}
    <div style="width:{{ column_width }}px"><table><tbody class="col">{{ tr }}</tbody></table></div>
    {% if not forloop.last %}
      {% if forloop.counter|divisibleby:columns_per_row %}  {# conclude the previous row and start another #}
        <!--[if true]></td></tr><tr><td style="width:{{ column_width }}px"><![endif]-->
      {% else %}  {# conclude the previous cell and start another #}
        <!--[if true]></td><td style="width:{{ column_width }}px"><![endif]-->
      {% endif %}
    {% endif %}
  {% endfor %}
  <!--[if true]></td></tr></tbody></table><![endif]-->
</div>

To use this template, I have to be able to feed in a list whose members contain column contents. The method that I've suggested is an efficient way of capturing all of these varied contents and passing them into the columns.html template. Here's an actual example of how I'm using this in a section that populates two rows of sponsor logos:

{% load my_tags %}
{% map company in companies as logos %}
  {% include 'newsletters/build/layouts/logo.html' with cls='logo' url=company.url logo=company.logo.get_thumb_url %}
{% endmap %}
{% include 'newsletters/build/layouts/columns.html' with column_trs=logos row_width=600 columns_per_row=4 %}

[codingjoe]

@codingjoe Do we document that __html__() usage?

@jacobtylerwalls yes, kind of. It is explititly named including its funciton. However, we never elaborate on the use case per object rendering explicitly. So, there's defnetly headroom to improve the docs.

[jacobtylerwalls]

Yeah, we ought to fix that -- I shut down after the "non-Django templates" wording.