Opened 9 years ago

Closed 9 years ago

Last modified 9 years ago

#5125 closed (fixed)

Add part about comparing values to templates documentation

Reported by: diogooo@… Owned by: nobody
Component: Documentation Version: master
Severity: Keywords: sprintsept14
Cc: Triage Stage: Ready for checkin
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

Sometimes we need to comparing values, like {% if value1 > value2 %}
but the templates documentation don't talk about this.

I tried to compare using '>' or '<', but i get an error message.
I just don't knew about 'lt' or 'gt'
Include this in template guides would be helpful for newbies like me :)

Tanks a lot.

Attachments (2)

templates.diff (1.4 KB) - added by Simon G. <dev@…> 9 years ago.
5125.diff (1.4 KB) - added by James Bennett 9 years ago.
New patch, hopefully clear explanation

Download all attachments as: .zip

Change History (13)

comment:1 Changed 9 years ago by James Bennett

Resolution: invalid
Status: newclosed

The template language is not Python; therefore, things which work in Python like ("if value 1 < value2") should not be expected to work in the template system.

comment:2 in reply to:  1 ; Changed 9 years ago by anonymous

Replying to ubernostrum:

The template language is not Python; therefore, things which work in Python like ("if value 1 < value2") should not be expected to work in the template system.

i knew that, but there is no mention of ("if value gt value") in templates doc.

comment:3 Changed 9 years ago by Simon G. <dev@…>

Needs documentation: set
Resolution: invalid
Status: closedreopened
Summary: comparing valuesAdd part about comparing values to templates documentation
Triage Stage: UnreviewedAccepted

That's a very good point. We should add that to the templates docs. Want to write up a few examples?

comment:4 in reply to:  2 Changed 9 years ago by James Bennett

Replying to anonymous:

i knew that, but there is no mention of ("if value gt value") in templates doc.

Well, the problem there is how far do we go listing possible Python constructs people might want to try in templates? There's literally an infinite number of them.

If there's a documentation update, it needs to be along the lines of:

The template language is intended to provide the minimal necessary set of features to allow you to express presentation; it is not a programming language, and is not the same as the Python programming language. If you're looking for a construct from Python -- operators, functions, method calls, etc. -- it probably will not be available in the template language, or will be implemented in a different form; for example, instead of Python's if construct there is an {% if %} template tag, and the template tag operates in a very different manner from the if construct in Python. If you don't see the feature you want listed on this page, it is not available by default in the template system (though you are free to define a custom template tag to implement it).

In other words, instead of encouraging an "assume the template system does it unless you hear otherwise" attitude, the docs need to point out that the correct view is "assume the template system does not do it unless you hear otherwise".

comment:5 Changed 9 years ago by Simon G. <dev@…>

Needs documentation: unset
Patch needs improvement: set
Triage Stage: AcceptedDesign decision needed

James, a flagged warning/note like yours above would be a great idea, although I'd try to explain why we do this (we don't want another PHP, logic goes into the view etc) as well. How's the attached patch?

Re: the gt/lt examples - hmm.. not sure what I was thinking w.r.t. the lt/gt documentation. I thought there was an implementation in Django. Must be my lack of sleep :)

Changed 9 years ago by Simon G. <dev@…>

Attachment: templates.diff added

comment:6 Changed 9 years ago by Anderson

I agree and im very happy that django is definitively not php,
but sometimes we need to do things like return the number of words in user posts,
and this is one of the basics features in blog apps for example.
After return that number, need to add a link like "view more >>".
I think that the templates is the right place for such comparison.

comment:7 in reply to:  6 Changed 9 years ago by James Bennett

Replying to Anderson:

I agree and im very happy that django is definitively not php,
but sometimes we need to do things like return the number of words in user posts,
and this is one of the basics features in blog apps for example.
After return that number, need to add a link like "view more >>".
I think that the templates is the right place for such comparison.

You probably want to go fetch a copy of template_utils, which includes tags written in the template system's preferred style which implement extra comparisons

Changed 9 years ago by James Bennett

Attachment: 5125.diff added

New patch, hopefully clear explanation

comment:8 Changed 9 years ago by James Bennett

Keywords: sprintsept14 added
Patch needs improvement: unset
Triage Stage: Design decision neededReady for checkin

Adding sprint keyword and bumping to "ready for checkin"; I think this is about the best we can do to deal concisely with assumptions about Python code working in templates without offending anyone.

comment:9 Changed 9 years ago by Malcolm Tredinnick

Resolution: fixed
Status: reopenedclosed

(In [6562]) Added a section to the template documentation to clarify the arbitrary Python
code should not be expected to work. The might help balance expectations.
Thanks, James Bennett. Fixed #5125.

comment:10 Changed 9 years ago by Gergely Kontra

What about changing the if tag to iftrue, just to hint users it is not a python if expression?

comment:11 Changed 9 years ago by James Bennett

No. Introducing a massive backwards-incompatible change like that is not an appropriate solution to the problem of people who don't bother to read the documentation.

Note: See TracTickets for help on using tickets.
Back to Top