Mercurial > p > roundup > code
comparison doc/reference.txt @ 8383:628794414f5f
doc: update doc on tal:replace and tal:content
Describe use of tal:replace for XSS and how to execute a replaced tag
with <tal:x> and tal:content.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sat, 12 Jul 2025 17:07:50 -0400 |
| parents | 586e49dda652 |
| children | e0e3212c1e80 |
comparison
equal
deleted
inserted
replaced
| 8382:109c1112c329 | 8383:628794414f5f |
|---|---|
| 2478 below on `the repeat variable`_. | 2478 below on `the repeat variable`_. |
| 2479 | 2479 |
| 2480 **tal:replace="expression"** | 2480 **tal:replace="expression"** |
| 2481 Replace this tag with the result of the expression. For example:: | 2481 Replace this tag with the result of the expression. For example:: |
| 2482 | 2482 |
| 2483 <span tal:replace="request/user/realname" /> | 2483 <span tal:replace="request/user/id" /> |
| 2484 | 2484 |
| 2485 The example would replace the <span> tag and its contents with the | 2485 The example would replace the <span> tag and its contents with the |
| 2486 user's realname. If the user's realname was "Bruce", then the | 2486 user's id. If the user's id was "3" the resulting output would be |
| 2487 resultant output would be "Bruce". | 2487 "3". |
| 2488 | |
| 2489 You need to be a little careful with ``tal:replace``. Unlike | |
| 2490 ``tal:content``, it doesn't always escape the output. For example | |
| 2491 if you used:: | |
| 2492 | |
| 2493 <tal:x tal:replace="request/user/realname" /> | |
| 2494 | |
| 2495 it would replace the contents with the value of the user's | |
| 2496 realname. The realname is something the user can control. The user | |
| 2497 could include something like:: | |
| 2498 | |
| 2499 Bruce<script>alert("hello there");</script> | |
| 2500 | |
| 2501 This would result in an alert box popping up when the page was | |
| 2502 loaded. Attackers could use this `XSS exploit`_ for malicious | |
| 2503 purposes. | |
| 2504 | |
| 2505 Generally you would use tal:replace when calling a utility function | |
| 2506 using a :ref:`Python expression <python expression>` that generates | |
| 2507 trusted HTML. | |
| 2508 | |
| 2509 If you are inserting untrusted content, it is better to use | |
| 2510 ``tal:content`` with tags that disappear as described below. | |
| 2511 | |
| 2512 .. _`XSS exploit`: https://owasp.org/www-community/attacks/xss/ | |
| 2488 | 2513 |
| 2489 **tal:content="expression"** | 2514 **tal:content="expression"** |
| 2490 Replace the contents of this tag with the result of the expression. | 2515 Replace the contents of this tag (but not the tag itself) with the |
| 2491 For example:: | 2516 result of the expression. For example:: |
| 2492 | 2517 |
| 2493 <span tal:content="request/user/realname">user's name appears here | 2518 <span tal:content="request/user/realname">user's name appears here |
| 2494 </span> | 2519 </span> |
| 2495 | 2520 |
| 2496 This example would replace the contents of the ``<span>`` tag with the | 2521 This example would replace the contents of the ``<span>`` tag with the |
| 2497 user's realname. If the user's realname was "Bruce" then the | 2522 user's realname. If the user's realname was "Bruce" then the |
| 2498 output will be ``<span>Bruce</span>``. | 2523 output will be ``<span>Bruce</span>``. |
| 2524 | |
| 2525 ``tal:content`` replaces special HTML claracters like ``<`` with an | |
| 2526 HTML entitity ``<``. This makes it safer to use when inserting | |
| 2527 untrusted data. To have ``tal:content`` insert unescaped HTML, you | |
| 2528 need to use the `structure modifier`_. | |
| 2529 | |
| 2530 If the tag is an unknown ``tal:`` tag, TAL removes the tag. So | |
| 2531 evaulating: | |
| 2532 | |
| 2533 <tal:x tal:replace="request/user/realname" /> | |
| 2534 | |
| 2535 results in ``Bruce``. | |
| 2499 | 2536 |
| 2500 **tal:attributes="attribute expression; attribute expression; ..."** | 2537 **tal:attributes="attribute expression; attribute expression; ..."** |
| 2501 Set attributes on this tag to the results of expressions. For | 2538 Set attributes on this tag to the results of expressions. For |
| 2502 example:: | 2539 example:: |
| 2503 | 2540 |
| 2572 expressions are string interpolations - though they can be | 2609 expressions are string interpolations - though they can be |
| 2573 just plain strings with no interpolation if you want. The | 2610 just plain strings with no interpolation if you want. The |
| 2574 expression in the interpolation decorator ``${ ... }`` is a | 2611 expression in the interpolation decorator ``${ ... }`` is a |
| 2575 path expression as above. | 2612 path expression as above. |
| 2576 | 2613 |
| 2614 .. _`python expression`: | |
| 2615 | |
| 2577 **Python Expressions** - e.g. ``python: 1+1`` | 2616 **Python Expressions** - e.g. ``python: 1+1`` |
| 2578 These expressions give the full power of Python. All the "root level" | 2617 These expressions give the full power of Python. All the "root level" |
| 2579 variables are available, so ``python:item.status.checklist()`` is | 2618 variables are available, so ``python:item.status.checklist()`` is |
| 2580 the same as ``item/status/checklist``, assuming that | 2619 the same as ``item/status/checklist``, assuming that |
| 2581 ``checklist`` is a method. | 2620 ``checklist`` is a method. |
| 2582 | 2621 |
| 2583 Modifiers: | 2622 Modifiers: |
| 2623 | |
| 2624 .. _`structure modifier`: | |
| 2584 | 2625 |
| 2585 **structure** - e.g. ``structure python:msg.content.plain(hyperlink=1)`` | 2626 **structure** - e.g. ``structure python:msg.content.plain(hyperlink=1)`` |
| 2586 The result of expressions are *escaped* to be safe for HTML | 2627 The result of expressions are *escaped* to be safe for HTML |
| 2587 display (all "<", ">" and "&" are replaced with entities | 2628 display (all "<", ">" and "&" are replaced with entities |
| 2588 (e.g. ``<``). The ``structure`` expression modifier turns | 2629 (e.g. ``<``). The ``structure`` expression modifier turns |