Clarify {% cache %} tag's handling of arguments

[Tom Aratyn]

The Django docs describe the use of the cache template tag:

It’s perfectly fine to specify more than one argument to identify the fragment. Simply pass as many arguments to {% cache %} as you need.

However the code will only use a single value (​https://github.com/django/django/blob/7cc155a04ce9579de3cdca59db9a4de11dc5eab9/django/templatetags/cache.py#L90):

    return CacheNode(vary_on = [var.resolve(context) for var in self.vary_on]
cache_key = make_template_fragment_key(self.fragment_name, vary_on)
        nodelist, parser.compile_filter(tokens[1]),
        tokens[2],  # fragment_name can't be a variable.
        [parser.compile_filter(t) for t in tokens[3:]],
        cache_name,
    )

What's more the example code in the docs uses an variable as part of the fragment name, but the code explicitly says that that doesn't work.

I'd prefer for the solution to be to bring the code inline with the docs, but at least the docs need updating.

[Tim Graham]

I think you misinterpreted the documentation. I've suggested ​a clarification. Let me know if it helps.

[Tom Aratyn]

Thanks for the quick turn around, Tim!

However, I don't think that patch is correct. I set a breakpoint on ​https://github.com/django/django/blob/master/django/templatetags/cache.py#L45 and I never see anything other than the third token being used as the fragment name (and therefore cache key).

I think the correct documentation might be to just say "you can only use a single string as your fragment key"... or fix the code to bring it inline with the docs.

My code has the following fragment:

  {% cache 300 "some fragment" "another fragment test"%}

and in the debugger I see that self.fragment_name is "some fragment" not a concatenation of the values. That makes sense, since on ​https://github.com/django/django/blob/master/django/templatetags/cache.py#L90 only the third token is passed as the fragment name.

[Tim Graham]

The additional arguments are passed to vary_on which is used to make cache_key.

[Tom Aratyn]

Replying to Tim Graham:

The additional arguments are passed to vary_on which is used to make cache_key.

Right. I had the word vary so locked into my head as the VARY header that I just blanked that out.

To make it explicit where you can and can't use variables, what do you think of ​https://github.com/django/django/pull/9285 ?

[Tim Graham <timograham@…>]

In 171c7cc8:

Fixed #28737 -- Clarified {% cache %} tag's handling of arguments.

Thanks Tom Aratyn for the report.

[Tim Graham <timograham@…>]

In 01987bc0:

[2.0.x] Fixed #28737 -- Clarified {% cache %} tag's handling of arguments.

Thanks Tom Aratyn for the report.

Backport of 171c7cc863eafc2346aa84ffd1d540644539f1a4 from master