Improve documentation for py:choose

[Sebastian Krysmanski <sebastian@…>]

I just tried to use <py:choose> but couldn't get it working. I had this code:

<py:choose test="option.type">
  <span py:when="text">...</span>
  <span py:otherwise="">...</span>
</py:choose>

However, the "otherwise" branch was always evaluated even when option.type (which is a string) had "text" as its value.

It took me a while to figure out that "text" in the py:when attribute is not a text but a variable name. The correct code should be (note the ticks in the attribute's value):

<py:choose test="option.type">
  <span py:when="'text'">...</span>
  <span py:otherwise="">...</span>
</py:choose>

Although it seems to be logical I think the documentation should include a note about working with strings (as the examples only work with numbers) to avoid this pitfall.

An alternative would be to fall back to evaluate the value of py:when as string rather than an expression. In this case my first example would work. Whether this is actually a good solution may be open to discussions.