Code

Opened 7 years ago

Closed 6 years ago

Last modified 6 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@…> 7 years ago.
5125.diff (1.4 KB) - added by ubernostrum 7 years ago.
New patch, hopefully clear explanation

Download all attachments as: .zip

Change History (13)

comment:1 follow-up: Changed 7 years ago by ubernostrum

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to invalid
  • Status changed from new to closed

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 ; follow-up: Changed 7 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 7 years ago by Simon G. <dev@…>

  • Needs documentation set
  • Resolution invalid deleted
  • Status changed from closed to reopened
  • Summary changed from comparing values to Add part about comparing values to templates documentation
  • Triage Stage changed from Unreviewed to Accepted

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 7 years ago by ubernostrum

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 7 years ago by Simon G. <dev@…>

  • Needs documentation unset
  • Patch needs improvement set
  • Triage Stage changed from Accepted to Design 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 7 years ago by Simon G. <dev@…>

comment:6 follow-up: Changed 7 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 7 years ago by ubernostrum

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 7 years ago by ubernostrum

New patch, hopefully clear explanation

comment:8 Changed 7 years ago by ubernostrum

  • Keywords sprintsept14 added
  • Patch needs improvement unset
  • Triage Stage changed from Design decision needed to Ready 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 6 years ago by mtredinnick

  • Resolution set to fixed
  • Status changed from reopened to closed

(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 6 years ago by pihentagy

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

comment:11 Changed 6 years ago by ubernostrum

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.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.