Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Reformatted docs/templates.txt to put headings in filter and tag refe…

…rences, so each tag/filter gets a permalink

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1110 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 92241e21b80efd0884730fb908c79eb45a847eac 1 parent 5defabc
Adrian Holovaty authored November 06, 2005

Showing 1 changed file with 575 additions and 442 deletions. Show diff stats Hide diff stats

  1. 1,017  docs/templates.txt
1,017  docs/templates.txt
@@ -289,567 +289,700 @@ available, and what they do.
289 289
 Built-in tag reference
290 290
 ----------------------
291 291
 
292  
-``block``
293  
-    Define a block that can be overridden by child templates. See `Template
294  
-    inheritance`_ for more information.
  292
+block
  293
+~~~~~
295 294
 
296  
-``comment``
297  
-    Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
  295
+Define a block that can be overridden by child templates. See
  296
+`Template inheritance`_ for more information.
298 297
 
299  
-``cycle``
300  
-    Cycle among the given strings each time this tag is encountered.
  298
+comment
  299
+~~~~~~~
301 300
 
302  
-    Within a loop, cycles among the given strings each time through
303  
-    the loop::
  301
+Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
304 302
 
305  
-        {% for o in some_list %}
306  
-            <tr class="{% cycle row1,row2 %}">
307  
-                ...
308  
-            </tr>
309  
-        {% endfor %}
  303
+cycle
  304
+~~~~~
310 305
 
311  
-    Outside of a loop, give the values a unique name the first time you call it,
312  
-    then use that name each successive time through::
  306
+Cycle among the given strings each time this tag is encountered.
313 307
 
314  
-            <tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
315  
-            <tr class="{% cycle rowcolors %}">...</tr>
316  
-            <tr class="{% cycle rowcolors %}">...</tr>
  308
+Within a loop, cycles among the given strings each time through the loop::
317 309
 
318  
-    You can use any number of values, separated by commas. Make sure not to put
319  
-    spaces between the values -- only commas.
  310
+    {% for o in some_list %}
  311
+        <tr class="{% cycle row1,row2 %}">
  312
+            ...
  313
+        </tr>
  314
+    {% endfor %}
  315
+
  316
+Outside of a loop, give the values a unique name the first time you call it,
  317
+then use that name each successive time through::
  318
+
  319
+        <tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
  320
+        <tr class="{% cycle rowcolors %}">...</tr>
  321
+        <tr class="{% cycle rowcolors %}">...</tr>
  322
+
  323
+You can use any number of values, separated by commas. Make sure not to put
  324
+spaces between the values -- only commas.
320 325
 
321  
-``debug``
322  
-    Output a whole load of debugging information, including the current context and
323  
-    imported modules.
  326
+debug
  327
+~~~~~
324 328
 
325  
-``extends``
326  
-    Signal that this template extends a parent template.
  329
+Output a whole load of debugging information, including the current context and
  330
+imported modules.
327 331
 
328  
-    This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
329  
-    the literal value "base" as the name of the parent template to extend, or ``{%
330  
-    extends variable %}`` uses the value of ``variable`` as the name of the parent
331  
-    template to extend.
  332
+extends
  333
+~~~~~~~
332 334
 
333  
-    See `Template inheritance`_ for more information.
  335
+Signal that this template extends a parent template.
334 336
 
335  
-``filter``
336  
-    Filter the contents of the variable through variable filters.
  337
+This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses
  338
+the literal value "base" as the name of the parent template to extend, or ``{%
  339
+extends variable %}`` uses the value of ``variable`` as the name of the parent
  340
+template to extend.
337 341
 
338  
-    Filters can also be piped through each other, and they can have arguments --
339  
-    just like in variable syntax.
  342
+See `Template inheritance`_ for more information.
340 343
 
341  
-    Sample usage::
  344
+filter
  345
+~~~~~~
342 346
 
343  
-        {% filter escape|lower %}
344  
-            This text will be HTML-escaped, and will appear in all lowercase.
345  
-        {% endfilter %}
  347
+Filter the contents of the variable through variable filters.
346 348
 
347  
-``firstof``
348  
-    Outputs the first variable passed that is not False.  Outputs nothing if all the
349  
-    passed variables are False.
  349
+Filters can also be piped through each other, and they can have arguments --
  350
+just like in variable syntax.
350 351
 
351  
-    Sample usage::
  352
+Sample usage::
352 353
 
353  
-        {% firstof var1 var2 var3 %}
  354
+    {% filter escape|lower %}
  355
+        This text will be HTML-escaped, and will appear in all lowercase.
  356
+    {% endfilter %}
354 357
 
355  
-    This is equivalent to::
  358
+firstof
  359
+~~~~~~~
356 360
 
357  
-        {% if var1 %}
358  
-            {{ var1 }}
359  
-        {% else %}{% if var2 %}
360  
-            {{ var2 }}
361  
-        {% else %}{% if var3 %}
362  
-            {{ var3 }}
363  
-        {% endif %}{% endif %}{% endif %}
  361
+Outputs the first variable passed that is not False.  Outputs nothing if all the
  362
+passed variables are False.
364 363
 
365  
-    but obviously much cleaner!
  364
+Sample usage::
366 365
 
367  
-``for``
368  
-    Loop over each item in an array.  For example, to display a list of athletes
369  
-    given ``athlete_list``::
  366
+    {% firstof var1 var2 var3 %}
370 367
 
  368
+This is equivalent to::
  369
+
  370
+    {% if var1 %}
  371
+        {{ var1 }}
  372
+    {% else %}{% if var2 %}
  373
+        {{ var2 }}
  374
+    {% else %}{% if var3 %}
  375
+        {{ var3 }}
  376
+    {% endif %}{% endif %}{% endif %}
  377
+
  378
+for
  379
+~~~
  380
+
  381
+Loop over each item in an array.  For example, to display a list of athletes
  382
+given ``athlete_list``::
  383
+
  384
+    <ul>
  385
+    {% for athlete in athlete_list %}
  386
+        <li>{{ athlete.name }}</li>
  387
+    {% endfor %}
  388
+    </ul>
  389
+
  390
+You can also loop over a list in reverse by using ``{% for obj in list reversed %}``.
  391
+
  392
+The for loop sets a number of variables available within the loop:
  393
+
  394
+    ==========================  ================================================
  395
+    Variable                    Description
  396
+    ==========================  ================================================
  397
+    ``forloop.counter``         The current iteration of the loop (1-indexed)
  398
+    ``forloop.counter0``        The current iteration of the loop (0-indexed)
  399
+    ``forloop.revcounter``      The number of iterations from the end of the
  400
+                                loop (1-indexed)
  401
+    ``forloop.revcounter0``     The number of iterations from the end of the
  402
+                                loop (0-indexed)
  403
+    ``forloop.first``           True if this is the first time through the loop
  404
+    ``forloop.last``            True if this is the last time through the loop
  405
+    ``forloop.parentloop``      For nested loops, this is the loop "above" the
  406
+                                current one
  407
+    ==========================  ================================================
  408
+
  409
+if
  410
+~~
  411
+
  412
+The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
  413
+exists, is not empty, and is not a false boolean value) the contents of the
  414
+block are output::
  415
+
  416
+    {% if athlete_list %}
  417
+        Number of athletes: {{ athlete_list|length }}
  418
+    {% else %}
  419
+        No athletes.
  420
+    {% endif %}
  421
+
  422
+In the above, if ``athlete_list`` is not empty, the number of athletes will be
  423
+displayed by the ``{{ athlete_list|length }}`` variable.
  424
+
  425
+As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
  426
+will be displayed if the test fails.
  427
+
  428
+``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
  429
+a given variable::
  430
+
  431
+    {% if not athlete_list %}
  432
+        There are no athletes.
  433
+    {% endif %}
  434
+
  435
+    {% if athlete_list or coach_list %}
  436
+        There are some athletes or some coaches.
  437
+    {% endif %}
  438
+
  439
+    {% if not athlete_list or coach_list %}
  440
+        There are no athletes or there are some coaches (OK, so
  441
+        writing English translations of boolean logic sounds
  442
+        stupid; it's not my fault).
  443
+    {% endif %}
  444
+
  445
+For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if``
  446
+tags instead::
  447
+
  448
+    {% if athlete_list %}
  449
+        {% if coach_list %}
  450
+            Number of athletes: {{ athlete_list|length }}.
  451
+            Number of coaches: {{ coach_list|length }}.
  452
+        {% endif %}
  453
+    {% endif %}
  454
+
  455
+ifchanged
  456
+~~~~~~~~~
  457
+
  458
+Check if a value has changed from the last iteration of a loop.
  459
+
  460
+The 'ifchanged' block tag is used within a loop. It checks its own rendered
  461
+contents against its previous state and only displays its content if the value
  462
+has changed::
  463
+
  464
+    <h1>Archive for {{ year }}</h1>
  465
+
  466
+    {% for day in days %}
  467
+    {% ifchanged %}<h3>{{ day|date:"F" }}</h3>{% endifchanged %}
  468
+    <a href="{{ day|date:"M/d"|lower }}/">{{ day|date:"j" }}</a>
  469
+    {% endfor %}
  470
+
  471
+ifequal
  472
+~~~~~~~
  473
+
  474
+Output the contents of the block if the two arguments equal each other.
  475
+
  476
+Example::
  477
+
  478
+    {% ifequal user.id comment.user_id %}
  479
+        ...
  480
+    {% endifequal %}
  481
+
  482
+As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional.
  483
+
  484
+The arguments can be hard-coded strings, so the following is valid::
  485
+
  486
+    {% ifequal user.username "adrian" %}
  487
+        ...
  488
+    {% endifequal %}
  489
+
  490
+ifnotequal
  491
+~~~~~~~~~~
  492
+
  493
+Just like ``ifequal``, except it tests that the two arguments are not equal.
  494
+
  495
+load
  496
+~~~~
  497
+
  498
+Load a custom template tag set.
  499
+
  500
+See `Custom tag and filter libraries`_ for more information.
  501
+
  502
+now
  503
+~~~
  504
+
  505
+Display the date, formatted according to the given string.
  506
+
  507
+Uses the same format as PHP's ``date()`` function (http://php.net/date)
  508
+with some custom extensions.
  509
+
  510
+Available format strings:
  511
+
  512
+================  ======================================  =====================
  513
+Format character  Description                             Example output
  514
+================  ======================================  =====================
  515
+a                 ``'a.m.'`` or ``'p.m.'`` (Note that     ``'a.m.'``
  516
+                    this is slightly different than PHP's
  517
+                    output, because this includes periods
  518
+                    to match Associated Press style.)
  519
+A                 ``'AM'`` or ``'PM'``.                   ``'AM'``
  520
+B                 Not implemented.
  521
+d                 Day of the month, 2 digits with         ``'01'`` to ``'31'``
  522
+                    leading zeros.
  523
+D                 Day of the week, textual, 3 letters.    ``'Fri'``
  524
+f                 Time, in 12-hour hours and minutes,     ``'1'``, ``'1:30'``
  525
+                    with minutes left off if they're zero.
  526
+                    Proprietary extension.
  527
+F                 Month, textual, long.                   ``'January'``
  528
+g                 Hour, 12-hour format without leading    ``'1'`` to ``'12'``
  529
+                    zeros.
  530
+G                 Hour, 24-hour format without leading    ``'0'`` to ``'23'``
  531
+                    zeros.
  532
+h                 Hour, 12-hour format.                   ``'01'`` to ``'12'``
  533
+H                 Hour, 24-hour format.                   ``'00'`` to ``'23'``
  534
+i                 Minutes.                                ``'00'`` to ``'59'``
  535
+I                 Not implemented.
  536
+j                 Day of the month without leading        ``'1'`` to ``'31'``
  537
+                    zeros.
  538
+l                 Day of the week, textual, long.         ``'Friday'``
  539
+L                 Boolean for whether it's a leap year.   ``True`` or ``False``
  540
+m                 Month, 2 digits with leading zeros.     ``'01'`` to ``'12'``
  541
+M                 Month, textual, 3 letters.              ``'Jan'``
  542
+n                 Month without leading zeros.            ``'1'`` to ``'12'``
  543
+N                 Month abbreviation in Associated Press  ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'``
  544
+                    style. Proprietary extension.
  545
+O                 Difference to Greenwich time in hours.  ``'+0200'``
  546
+P                 Time, in 12-hour hours, minutes and     ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'``
  547
+                    'a.m.'/'p.m.', with minutes left off
  548
+                    if they're zero and the special-case
  549
+                    strings 'midnight' and 'noon' if
  550
+                    appropriate. Proprietary extension.
  551
+r                 RFC 822 formatted date.                 ``'Thu, 21 Dec 2000 16:01:07 +0200'``
  552
+s                 Seconds, 2 digits with leading zeros.   ``'00'`` to ``'59'``
  553
+S                 English ordinal suffix for day of the   ``'st'``, ``'nd'``, ``'rd'`` or ``'th'``
  554
+                    month, 2 characters.
  555
+t                 Not implemented.
  556
+T                 Time zone of this machine.              ``'EST'``, ``'MDT'``
  557
+U                 Not implemented.
  558
+w                 Day of the week, digits without         ``'0'`` (Sunday) to ``'6'`` (Saturday)
  559
+                    leading zeros.
  560
+W                 ISO-8601 week number of year, with      ``1``, ``23``
  561
+                    weeks starting on Monday.
  562
+y                 Year, 2 digits.                         ``'99'``
  563
+Y                 Year, 4 digits.                         ``'1999'``
  564
+z                 Day of the year.                        ``0`` to ``365``
  565
+Z                 Time zone offset in seconds. The        ``-43200`` to ``43200``
  566
+                    offset for timezones west of UTC is
  567
+                    always negative, and for those east of
  568
+                    UTC is always positive.
  569
+================  ======================================  =====================
  570
+
  571
+Example::
  572
+
  573
+    It is {% now "jS F Y H:i" %}
  574
+
  575
+Note that you can backslash-escape a format string if you want to use the
  576
+"raw" value. In this example, "f" is backslash-escaped, because otherwise
  577
+"f" is a format string that displays the time. The "o" doesn't need to be
  578
+escaped, because it's not a format character.::
  579
+
  580
+    It is the {% "jS o\f F" %}
  581
+
  582
+(Displays "It is the 4th of September" %}
  583
+
  584
+regroup
  585
+~~~~~~~
  586
+
  587
+Regroup a list of alike objects by a common attribute.
  588
+
  589
+This complex tag is best illustrated by use of an example:  say that ``people``
  590
+is a list of ``Person`` objects that have ``first_name``, ``last_name``, and
  591
+``gender`` attributes, and you'd like to display a list that looks like:
  592
+
  593
+    * Male:
  594
+        * George Bush
  595
+        * Bill Clinton
  596
+    * Female:
  597
+        * Margaret Thatcher
  598
+        * Condoleezza Rice
  599
+    * Unknown:
  600
+        * Pat Smith
  601
+
  602
+The following snippet of template code would accomplish this dubious task::
  603
+
  604
+    {% regroup people by gender as grouped %}
  605
+    <ul>
  606
+    {% for group in grouped %}
  607
+        <li>{{ group.grouper }}
371 608
         <ul>
372  
-        {% for athlete in athlete_list %}
373  
-            <li>{{ athlete.name }}</li>
374  
-        {% endfor %}
  609
+            {% for item in group.list %}
  610
+            <li>{{ item }}</li>
  611
+            {% endfor %}
375 612
         </ul>
  613
+    {% endfor %}
  614
+    </ul>
376 615
 
377  
-    You can also loop over a list in reverse by using ``{% for obj in list reversed %}``.
378  
-
379  
-    The for loop sets a number of variables available within the loop:
380  
-
381  
-        ==========================  ================================================
382  
-        Variable                    Description
383  
-        ==========================  ================================================
384  
-        ``forloop.counter``         The current iteration of the loop (1-indexed)
385  
-        ``forloop.counter0``        The current iteration of the loop (0-indexed)
386  
-        ``forloop.revcounter``      The number of iterations from the end of the
387  
-                                    loop (1-indexed)
388  
-        ``forloop.revcounter0``     The number of iterations from the end of the
389  
-                                    loop (0-indexed)
390  
-        ``forloop.first``           True if this is the first time through the loop
391  
-        ``forloop.last``            True if this is the last time through the loop
392  
-        ``forloop.parentloop``      For nested loops, this is the loop "above" the
393  
-                                    current one
394  
-        ==========================  ================================================
395  
-
396  
-``if``
397  
-    The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
398  
-    exists, is not empty, and is not a false boolean value) the contents of the
399  
-    block are output::
400  
-
401  
-        {% if athlete_list %}
402  
-            Number of athletes: {{ athlete_list|length }}
403  
-        {% else %}
404  
-            No athletes.
405  
-        {% endif %}
  616
+As you can see, ``{% regroup %}`` populates a variable with a list of objects
  617
+with ``grouper`` and ``list`` attributes.  ``grouper`` contains the item that
  618
+was grouped by; ``list`` contains the list of objects that share that
  619
+``grouper``.  In this case, ``grouper`` would be ``Male``, ``Female`` and
  620
+``Unknown``, and ``list`` is the list of people with those genders.
406 621
 
407  
-    In the above, if ``athlete_list`` is not empty, the number of athletes will be
408  
-    displayed by the ``{{ athlete_list|length }}`` variable.
  622
+Note that ``{% regroup %}`` does not work when the list to be grouped is not
  623
+sorted by the key you are grouping by!  This means that if your list of people
  624
+was not sorted by gender, you'd need to make sure it is sorted before using it,
  625
+i.e.::
409 626
 
410  
-    As you can see, the ``if`` tag can take an option ``{% else %}`` clause that
411  
-    will be displayed if the test fails.
  627
+    {% regroup people|dictsort:"gender" by gender as grouped %}
412 628
 
413  
-    ``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate
414  
-    a given variable::
  629
+ssi
  630
+~~~
415 631
 
416  
-        {% if not athlete_list %}
417  
-            There are no athletes.
418  
-        {% endif %}
  632
+Output the contents of a given file into the page.
419 633
 
420  
-        {% if athlete_list or coach_list %}
421  
-            There are some athletes or some coaches.
422  
-        {% endif %}
  634
+Like a simple "include" tag, ``{% ssi %}`` includes the contents of another
  635
+file -- which must be specified using an absolute path -- in the current
  636
+page::
423 637
 
424  
-        {% if not athlete_list or coach_list %}
425  
-            There are no athletes or there are some coaches (OK, so
426  
-            writing English translations of boolean logic sounds
427  
-            stupid; it's not my fault).
428  
-        {% endif %}
  638
+    {% ssi /home/html/ljworld.com/includes/right_generic.html %}
429 639
 
430  
-    For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if``
431  
-    tags instead::
  640
+If the optional "parsed" parameter is given, the contents of the included
  641
+file are evaluated as template code, within the current context::
432 642
 
433  
-        {% if athlete_list %}
434  
-            {% if coach_list %}
435  
-                Number of athletes: {{ athlete_list|length }}.
436  
-                Number of coaches: {{ coach_list|length }}.
437  
-            {% endif %}
438  
-        {% endif %}
  643
+    {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
439 644
 
440  
-``ifchanged``
441  
-    Check if a value has changed from the last iteration of a loop.
  645
+Note that if you use ``{% ssi %}``, you'll need to define
  646
+`ALLOWED_INCLUDE_ROOTS`_ in your Django settings, as a security measure.
442 647
 
443  
-    The 'ifchanged' block tag is used within a loop. It checks its own rendered
444  
-    contents against its previous state and only displays its content if the value
445  
-    has changed::
  648
+.. _ALLOWED_INCLUDE_ROOTS: http://www.djangoproject.com/documentation/settings/#allowed-include-roots
446 649
 
447  
-        <h1>Archive for {{ year }}</h1>
  650
+templatetag
  651
+~~~~~~~~~~~
448 652
 
449  
-        {% for day in days %}
450  
-        {% ifchanged %}<h3>{{ day|date:"F" }}</h3>{% endifchanged %}
451  
-        <a href="{{ day|date:"M/d"|lower }}/">{{ day|date:"j" }}</a>
452  
-        {% endfor %}
  653
+Output one of the syntax characters used to compose template tags.
453 654
 
454  
-``ifequal``
455  
-    Output the contents of the block if the two arguments equal each other.
  655
+Since the template system has no concept of "escaping", to display one of the
  656
+bits used in template tags, you must use the ``{% templatetag %}`` tag.
456 657
 
457  
-    Example::
  658
+The argument tells which template bit to output:
458 659
 
459  
-        {% ifequal user.id comment.user_id %}
460  
-            ...
461  
-        {% endifequal %}
  660
+    ==================  =======
  661
+    Argument            Outputs
  662
+    ==================  =======
  663
+    ``openblock``       ``{%``
  664
+    ``closeblock``      ``%}``
  665
+    ``openvariable``    ``{{``
  666
+    ``closevariable``   ``}}``
  667
+    ==================  =======
462 668
 
463  
-    As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional.
  669
+widthratio
  670
+~~~~~~~~~~
464 671
 
465  
-    The arguments can be hard-coded strings, so the following is valid::
  672
+For creating bar charts and such, this tag calculates the ratio of a given value
  673
+to a maximum value, and then applies that ratio to a constant.
466 674
 
467  
-        {% ifequal user.username "adrian" %}
468  
-            ...
469  
-        {% endifequal %}
470  
-
471  
-``ifnotequal``
472  
-    Just like ``ifequal``, except it tests that the two arguments are not equal.
473  
-
474  
-``load``
475  
-    Load a custom template tag set.
476  
-
477  
-    See `Custom tag and filter libraries`_ for more information.
478  
-
479  
-``now``
480  
-    Display the date, formatted according to the given string.
481  
-
482  
-    Uses the same format as PHP's ``date()`` function (http://php.net/date)
483  
-    with some custom extensions.
484  
-
485  
-    Available format strings:
486  
-
487  
-    ================  ======================================  =====================
488  
-    Format character  Description                             Example output
489  
-    ================  ======================================  =====================
490  
-    a                 ``'a.m.'`` or ``'p.m.'`` (Note that     ``'a.m.'``
491  
-                      this is slightly different than PHP's
492  
-                      output, because this includes periods
493  
-                      to match Associated Press style.)
494  
-    A                 ``'AM'`` or ``'PM'``.                   ``'AM'``
495  
-    B                 Not implemented.
496  
-    d                 Day of the month, 2 digits with         ``'01'`` to ``'31'``
497  
-                      leading zeros.
498  
-    D                 Day of the week, textual, 3 letters.    ``'Fri'``
499  
-    f                 Time, in 12-hour hours and minutes,     ``'1'``, ``'1:30'``
500  
-                      with minutes left off if they're zero.
501  
-                      Proprietary extension.
502  
-    F                 Month, textual, long.                   ``'January'``
503  
-    g                 Hour, 12-hour format without leading    ``'1'`` to ``'12'``
504  
-                      zeros.
505  
-    G                 Hour, 24-hour format without leading    ``'0'`` to ``'23'``
506  
-                      zeros.
507  
-    h                 Hour, 12-hour format.                   ``'01'`` to ``'12'``
508  
-    H                 Hour, 24-hour format.                   ``'00'`` to ``'23'``
509  
-    i                 Minutes.                                ``'00'`` to ``'59'``
510  
-    I                 Not implemented.
511  
-    j                 Day of the month without leading        ``'1'`` to ``'31'``
512  
-                      zeros.
513  
-    l                 Day of the week, textual, long.         ``'Friday'``
514  
-    L                 Boolean for whether it's a leap year.   ``True`` or ``False``
515  
-    m                 Month, 2 digits with leading zeros.     ``'01'`` to ``'12'``
516  
-    M                 Month, textual, 3 letters.              ``'Jan'``
517  
-    n                 Month without leading zeros.            ``'1'`` to ``'12'``
518  
-    N                 Month abbreviation in Associated Press  ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'``
519  
-                      style. Proprietary extension.
520  
-    O                 Difference to Greenwich time in hours.  ``'+0200'``
521  
-    P                 Time, in 12-hour hours, minutes and     ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'``
522  
-                      'a.m.'/'p.m.', with minutes left off
523  
-                      if they're zero and the special-case
524  
-                      strings 'midnight' and 'noon' if
525  
-                      appropriate. Proprietary extension.
526  
-    r                 RFC 822 formatted date.                 ``'Thu, 21 Dec 2000 16:01:07 +0200'``
527  
-    s                 Seconds, 2 digits with leading zeros.   ``'00'`` to ``'59'``
528  
-    S                 English ordinal suffix for day of the   ``'st'``, ``'nd'``, ``'rd'`` or ``'th'``
529  
-                      month, 2 characters.
530  
-    t                 Not implemented.
531  
-    T                 Time zone of this machine.              ``'EST'``, ``'MDT'``
532  
-    U                 Not implemented.
533  
-    w                 Day of the week, digits without         ``'0'`` (Sunday) to ``'6'`` (Saturday)
534  
-                      leading zeros.
535  
-    W                 ISO-8601 week number of year, with      ``1``, ``23``
536  
-                      weeks starting on Monday.
537  
-    y                 Year, 2 digits.                         ``'99'``
538  
-    Y                 Year, 4 digits.                         ``'1999'``
539  
-    z                 Day of the year.                        ``0`` to ``365``
540  
-    Z                 Time zone offset in seconds. The        ``-43200`` to ``43200``
541  
-                      offset for timezones west of UTC is
542  
-                      always negative, and for those east of
543  
-                      UTC is always positive.
544  
-    ================  ======================================  =====================
545  
-
546  
-    Example::
547  
-
548  
-        It is {% now "jS F Y H:i" %}
549  
-
550  
-    Note that you can backslash-escape a format string if you want to use the
551  
-    "raw" value. In this example, "f" is backslash-escaped, because otherwise
552  
-    "f" is a format string that displays the time. The "o" doesn't need to be
553  
-    escaped, because it's not a format character.::
554  
-
555  
-        It is the {% "jS o\f F" %}
556  
-
557  
-    (Displays "It is the 4th of September" %}
558  
-
559  
-``regroup``
560  
-    Regroup a list of alike objects by a common attribute.
561  
-
562  
-    This complex tag is best illustrated by use of an example:  say that ``people``
563  
-    is a list of ``Person`` objects that have ``first_name``, ``last_name``, and
564  
-    ``gender`` attributes, and you'd like to display a list that looks like:
565  
-
566  
-        * Male:
567  
-            * George Bush
568  
-            * Bill Clinton
569  
-        * Female:
570  
-            * Margaret Thatcher
571  
-            * Condoleezza Rice
572  
-        * Unknown:
573  
-            * Pat Smith
574  
-
575  
-    The following snippet of template code would accomplish this dubious task::
576  
-
577  
-        {% regroup people by gender as grouped %}
578  
-        <ul>
579  
-        {% for group in grouped %}
580  
-            <li>{{ group.grouper }}
581  
-            <ul>
582  
-                {% for item in group.list %}
583  
-                <li>{{ item }}</li>
584  
-                {% endfor %}
585  
-            </ul>
586  
-        {% endfor %}
587  
-        </ul>
  675
+For example::
588 676
 
589  
-    As you can see, ``{% regroup %}`` populates a variable with a list of objects
590  
-    with ``grouper`` and ``list`` attributes.  ``grouper`` contains the item that
591  
-    was grouped by; ``list`` contains the list of objects that share that
592  
-    ``grouper``.  In this case, ``grouper`` would be ``Male``, ``Female`` and
593  
-    ``Unknown``, and ``list`` is the list of people with those genders.
  677
+    <img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' />
594 678
 
595  
-    Note that ``{% regroup %}`` does not work when the list to be grouped is not
596  
-    sorted by the key you are grouping by!  This means that if your list of people
597  
-    was not sorted by gender, you'd need to make sure it is sorted before using it,
598  
-    i.e.::
  679
+Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the
  680
+above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
  681
+which is rounded up to 88).
599 682
 
600  
-        {% regroup people|dictsort:"gender" by gender as grouped %}
  683
+Built-in filter reference
  684
+-------------------------
601 685
 
602  
-``ssi``
603  
-    Output the contents of a given file into the page.
  686
+add
  687
+~~~
604 688
 
605  
-    Like a simple "include" tag, ``{% ssi %}`` includes the contents of another
606  
-    file -- which must be specified using an absolute path -- in the current
607  
-    page::
  689
+Adds the arg to the value.
608 690
 
609  
-        {% ssi /home/html/ljworld.com/includes/right_generic.html %}
  691
+addslashes
  692
+~~~~~~~~~~
610 693
 
611  
-    If the optional "parsed" parameter is given, the contents of the included
612  
-    file are evaluated as template code, within the current context::
  694
+Adds slashes. Useful for passing strings to JavaScript, for example.
613 695
 
614  
-        {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}
615 696
 
616  
-    Note that if you use ``{% ssi %}``, you'll need to define
617  
-    `ALLOWED_INCLUDE_ROOTS`_ in your Django settings, as a security measure.
  697
+capfirst
  698
+~~~~~~~~
618 699
 
619  
-.. _ALLOWED_INCLUDE_ROOTS: http://www.djangoproject.com/documentation/settings/#allowed-include-roots
  700
+Capitalizes the first character of the value.
620 701
 
621  
-``templatetag``
622  
-    Output one of the bits used to compose template tags.
  702
+center
  703
+~~~~~~
623 704
 
624  
-    Since the template system has no concept of "escaping", to display one of the
625  
-    bits used in template tags, you must use the ``{% templatetag %}`` tag.
  705
+Centers the value in a field of a given width.
626 706
 
627  
-    The argument tells which template bit to output:
  707
+cut
  708
+~~~
628 709
 
629  
-        ==================  =======
630  
-        Argument            Outputs
631  
-        ==================  =======
632  
-        ``openblock``       ``{%``
633  
-        ``closeblock``      ``%}``
634  
-        ``openvariable``    ``{{``
635  
-        ``closevariable``   ``}}``
636  
-        ==================  =======
  710
+Removes all values of arg from the given string.
637 711
 
638  
-``widthratio``
639  
-    For creating bar charts and such, this tag calculates the ratio of a given value
640  
-    to a maximum value, and then applies that ratio to a constant.
  712
+date
  713
+~~~~
641 714
 
642  
-    For example::
  715
+Formats a date according to the given format (same as the ``now`` tag).
643 716
 
644  
-        <img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' />
  717
+default
  718
+~~~~~~~
645 719
 
646  
-    Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the
647  
-    above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
648  
-    which is rounded up to 88).
  720
+If value is unavailable, use given default.
649 721
 
650  
-Built-in filter reference
651  
--------------------------
  722
+default_if_none
  723
+~~~~~~~~~~~~~~~
652 724
 
653  
-``add``
654  
-    Adds the arg to the value.
  725
+If value is ``None``, use given default.
655 726
 
656  
-``addslashes``
657  
-    Adds slashes. Useful for passing strings to JavaScript, for example.
  727
+dictsort
  728
+~~~~~~~~
658 729
 
659  
-``capfirst``
660  
-    Capitalizes the first character of the value.
  730
+Takes a list of dicts, returns that list sorted by the property given in the
  731
+argument.
661 732
 
662  
-``center``
663  
-    Centers the value in a field of a given width.
  733
+dictsortreversed
  734
+~~~~~~~~~~~~~~~~
664 735
 
665  
-``cut``
666  
-    Removes all values of arg from the given string.
  736
+Takes a list of dicts, returns that list sorted in reverse order by the
  737
+property given in the argument.
667 738
 
668  
-``date``
669  
-    Formats a date according to the given format (same as the ``now`` tag).
  739
+divisibleby
  740
+~~~~~~~~~~~
670 741
 
671  
-``default``
672  
-    If value is unavailable, use given default.
  742
+Returns true if the value is divisible by the argument.
673 743
 
674  
-``default_if_none``
675  
-    If value is ``None``, use given default.
  744
+escape
  745
+~~~~~~
676 746
 
677  
-``dictsort``
678  
-    Takes a list of dicts, returns that list sorted by the property given in the
679  
-    argument.
  747
+Escapes a string's HTML. Specifically, it makes these replacements:
680 748
 
681  
-``dictsortreversed``
682  
-    Takes a list of dicts, returns that list sorted in reverse order by the property
683  
-    given in the argument.
  749
+    * ``"&"`` to ``"&amp;"``
  750
+    * ``<`` to ``"&lt;"``
  751
+    * ``>`` to ``"&gt;"``
  752
+    * ``'"'`` (double quote) to ``"&quot;"``
684 753
 
685  
-``divisibleby``
686  
-    Returns true if the value is divisible by the argument.
  754
+filesizeformat
  755
+~~~~~~~~~~~~~~
687 756
 
688  
-``escape``
689  
-    Escapes a string's HTML.
  757
+Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
  758
+bytes, etc).
690 759
 
691  
-``filesizeformat``
692  
-    Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102
693  
-    bytes, etc).
  760
+first
  761
+~~~~~
694 762
 
695  
-``first``
696  
-    Returns the first item in a list.
  763
+Returns the first item in a list.
697 764
 
698  
-``fix_ampersands``
699  
-    Replaces ampersands with ``&amp;`` entities.
  765
+fix_ampersands
  766
+~~~~~~~~~~~~~~
700 767
 
701  
-``floatformat``
702  
-    Displays a floating point number as 34.2 (with one decimal places) - but
703  
-    only if there's a point to be displayed.
  768
+Replaces ampersands with ``&amp;`` entities.
704 769
 
705  
-``get_digit``
706  
-    Given a whole number, returns the requested digit of it, where 1 is the
707  
-    right-most digit, 2 is the second-right-most digit, etc. Returns the
708  
-    original value for invalid input (if input or argument is not an integer,
709  
-    or if argument is less than 1). Otherwise, output is always an integer.
  770
+floatformat
710 771
 
711  
-``join``
712  
-    Joins a list with a string, like Python's ``str.join(list)``.
  772
+Displays a floating point number as 34.2 (with one decimal places) -- but only
  773
+if there's a point to be displayed.
713 774
 
714  
-``length``
715  
-    Returns the length of the value. Useful for lists.
  775
+get_digit
  776
+~~~~~~~~~
716 777
 
717  
-``length_is``
718  
-    Returns a boolean of whether the value's length is the argument.
  778
+Given a whole number, returns the requested digit of it, where 1 is the
  779
+right-most digit, 2 is the second-right-most digit, etc. Returns the original
  780
+value for invalid input (if input or argument is not an integer, or if argument
  781
+is less than 1). Otherwise, output is always an integer.
719 782
 
720  
-``linebreaks``
721  
-    Converts newlines into <p> and <br />s.
  783
+join
  784
+~~~~
722 785
 
723  
-``linebreaksbr``
724  
-    Converts newlines into <br />s.
  786
+Joins a list with a string, like Python's ``str.join(list)``.
725 787
 
726  
-``linenumbers``
727  
-    Displays text with line numbers.
  788
+length
  789
+~~~~~~
728 790
 
729  
-``ljust``
730  
-    Left-aligns the value in a field of a given width.
  791
+Returns the length of the value. Useful for lists.
731 792
 
732  
-    **Argument:** field size
  793
+length_is
  794
+~~~~~~~~~
733 795
 
734  
-``lower``
735  
-    Converts a string into all lowercase.
  796
+Returns a boolean of whether the value's length is the argument.
736 797
 
737  
-``make_list``
738  
-    Returns the value turned into a list. For an integer, it's a list of
739  
-    digits. For a string, it's a list of characters.
  798
+linebreaks
  799
+~~~~~~~~~~
740 800
 
741  
-``phone2numeric``
742  
-    Takes a phone number and converts it in to its numerical equivalent.
  801
+Converts newlines into <p> and <br />s.
743 802
 
744  
-``pluralize``
745  
-    Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'.
  803
+linebreaksbr
  804
+~~~~~~~~~~~~
746 805
 
747  
-``pprint``
748  
-    A wrapper around pprint.pprint -- for debugging, really.
  806
+Converts newlines into <br />s.
749 807
 
750  
-``random``
751  
-    Returns a random item from the list.
  808
+linenumbers
  809
+~~~~~~~~~~~
752 810
 
753  
-``removetags``
754  
-    Removes a space separated list of [X]HTML tags from the output.
  811
+Displays text with line numbers.
755 812
 
756  
-``rjust``
757  
-    Right-aligns the value in a field of a given width.
  813
+ljust
  814
+~~~~~
758 815
 
759  
-    **Argument:** field size
  816
+Left-aligns the value in a field of a given width.
760 817
 
761  
-``slice``
762  
-    Returns a slice of the list.
  818
+**Argument:** field size
763 819
 
764  
-    Uses the same syntax as Python's list slicing; see
765  
-    http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
766  
-    for an introduction.
  820
+lower
  821
+~~~~~
767 822
 
768  
-    Example: ``{{ some_list|slice:":2" }}``
  823
+Converts a string into all lowercase.
769 824
 
770  
-``slugify``
771  
-    Converts to lowercase, removes non-word characters (alphanumerics and
772  
-    underscores) and converts spaces to hyphens. Also strips leading and
773  
-    trailing whitespace.
  825
+make_list
  826
+~~~~~~~~~
774 827
 
775  
-``stringformat``
776  
-    Formats the variable according to the argument, a string formatting specifier.
777  
-    This specifier uses Python string formating syntax, with the exception that
778  
-    the leading "%" is dropped.
  828
+Returns the value turned into a list. For an integer, it's a list of
  829
+digits. For a string, it's a list of characters.
779 830
 
780  
-    See http://docs.python.org/lib/typesseq-strings.html for documentation
781  
-    of Python string formatting
  831
+phone2numeric
  832
+~~~~~~~~~~~~~
782 833
 
783  
-``striptags``
784  
-    Strips all [X]HTML tags.
  834
+Converts a phone number to its numerical equivalent.
785 835
 
786  
-``time``
787  
-    Formats a time according to the given format (same as the ``now`` tag).
  836
+pluralize
  837
+~~~~~~~~~
788 838
 
789  
-``timesince``
790  
-    Formats a date as the time since that date (i.e. "4 days, 6 hours").
  839
+Returns 's' if the value is not 1, for '1 vote' vs. '2 votes'.
791 840
 
792  
-``title``
793  
-    Converts a string into titlecase.
  841
+pprint
  842
+~~~~~~
794 843
 
795  
-``truncatewords``
796  
-    Truncates a string after a certain number of words.
  844
+A wrapper around pprint.pprint -- for debugging, really.
797 845
 
798  
-    **Argument:** Number of words to truncate after
  846
+random
  847
+~~~~~~
799 848
 
800  
-``unordered_list``
801  
-    Recursively takes a self-nested list and returns an HTML unordered list --
802  
-    WITHOUT opening and closing <ul> tags.
  849
+Returns a random item from the list.
803 850
 
804  
-    The list is assumed to be in the proper format. For example, if ``var`` contains
805  
-    ``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
806  
-    then ``{{ var|unordered_list }}`` would return::
  851
+removetags
  852
+~~~~~~~~~~
807 853
 
808  
-        <li>States
809  
-        <ul>
810  
-                <li>Kansas
811  
-                <ul>
812  
-                        <li>Lawrence</li>
813  
-                        <li>Topeka</li>
814  
-                </ul>
815  
-                </li>
816  
-                <li>Illinois</li>
817  
-        </ul>
818  
-        </li>
  854
+Removes a space separated list of [X]HTML tags from the output.
  855
+
  856
+rjust
  857
+~~~~~
  858
+
  859
+Right-aligns the value in a field of a given width.
  860
+
  861
+**Argument:** field size
  862
+
  863
+slice
  864
+~~~~~
  865
+
  866
+Returns a slice of the list.
  867
+
  868
+Uses the same syntax as Python's list slicing. See
  869
+http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice
  870
+for an introduction.
  871
+
  872
+Example: ``{{ some_list|slice:":2" }}``
  873
+
  874
+slugify
  875
+~~~~~~~
  876
+
  877
+Converts to lowercase, removes non-word characters (alphanumerics and
  878
+underscores) and converts spaces to hyphens. Also strips leading and trailing
  879
+whitespace.
  880
+
  881
+stringformat
  882
+~~~~~~~~~~~~
  883
+
  884
+Formats the variable according to the argument, a string formatting specifier.
  885
+This specifier uses Python string formating syntax, with the exception that
  886
+the leading "%" is dropped.
  887
+
  888
+See http://docs.python.org/lib/typesseq-strings.html for documentation of
  889
+Python string formatting
  890
+
  891
+striptags
  892
+~~~~~~~~~
  893
+
  894
+Strips all [X]HTML tags.
  895
+
  896
+time
  897
+~~~~
  898
+
  899
+Formats a time according to the given format (same as the ``now`` tag).
  900
+
  901
+timesince
  902
+~~~~~~~~~
  903
+
  904
+Formats a date as the time since that date (i.e. "4 days, 6 hours").
  905
+
  906
+title
  907
+~~~~~
  908
+
  909
+Converts a string into titlecase.
  910
+
  911
+truncatewords
  912
+~~~~~~~~~~~~~
  913
+
  914
+Truncates a string after a certain number of words.
  915
+
  916
+**Argument:** Number of words to truncate after
  917
+
  918
+unordered_list
  919
+~~~~~~~~~~~~~~
  920
+
  921
+Recursively takes a self-nested list and returns an HTML unordered list --
  922
+WITHOUT opening and closing <ul> tags.
  923
+
  924
+The list is assumed to be in the proper format. For example, if ``var`` contains
  925
+``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``,
  926
+then ``{{ var|unordered_list }}`` would return::
  927
+
  928
+    <li>States
  929
+    <ul>
  930
+            <li>Kansas
  931
+            <ul>
  932
+                    <li>Lawrence</li>
  933
+                    <li>Topeka</li>
  934
+            </ul>
  935
+            </li>
  936
+            <li>Illinois</li>
  937
+    </ul>
  938
+    </li>
  939
+
  940
+upper
  941
+~~~~~
  942
+
  943
+Converts a string into all uppercase.
  944
+
  945
+urlencode
  946
+~~~~~~~~~
  947
+
  948
+Escapes a value for use in a URL.
  949
+
  950
+urlize
  951
+~~~~~~
  952
+
  953
+Converts URLs in plain text into clickable links.
  954
+
  955
+urlizetrunc
  956
+~~~~~~~~~~~
819 957
 
820  
-``upper``
821  
-    Converts a string into all uppercase.
  958
+Converts URLs into clickable links, truncating URLs to the given character limit.
822 959
 
823  
-``urlencode``
824  
-    Escapes a value for use in a URL.
  960
+**Argument:** Length to truncate URLs to
825 961
 
826  
-``urlize``
827  
-    Converts URLs in plain text into clickable links.
  962
+wordcount
  963
+~~~~~~~~~
828 964
 
829  
-``urlizetrunc``
830  
-    Converts URLs into clickable links, truncating URLs to the given character
831  
-    limit.
  965
+Returns the number of words.
832 966
 
833  
-    **Argument:** Length to truncate URLs to
  967
+wordwrap
  968
+~~~~~~~~
834 969
 
835  
-``wordcount``
836  
-    Returns the number of words.
  970
+Wraps words at specified line length.
837 971
 
838  
-``wordwrap``
839  
-    Wraps words at specified line length.
  972
+**Argument:** number of words at which to wrap the text
840 973
 
841  
-    **Argument:** number of words at which to wrap the text
  974
+yesno
  975
+~~~~~
842 976
 
843  
-``yesno``
844  
-    Given a string mapping values for true, false and (optionally) None,
845  
-    returns one of those strings according to the value:
  977
+Given a string mapping values for true, false and (optionally) None,
  978
+returns one of those strings according to the value:
846 979
 
847  
-    ==========  ======================  ==================================
848  
-    Value       Argument                Outputs
849  
-    ==========  ======================  ==================================
850  
-    ``True``    ``"yeah,no,maybe"``     ``yeah``
851  
-    ``False``   ``"yeah,no,maybe"``     ``no``
852  
-    ``None``    ``"yeah,no,maybe"``     ``maybe``
853  
-    ``None``    ``"yeah,no"``           ``"no"`` (converts None to False
854  
-                                        if no mapping for None is given)
855  
-    ==========  ======================  ==================================
  980
+==========  ======================  ==================================
  981
+Value       Argument                Outputs
  982
+==========  ======================  ==================================
  983
+``True``    ``"yeah,no,maybe"``     ``yeah``
  984
+``False``   ``"yeah,no,maybe"``     ``no``
  985
+``None``    ``"yeah,no,maybe"``     ``maybe``
  986
+``None``    ``"yeah,no"``           ``"no"`` (converts None to False
  987
+                                    if no mapping for None is given)
  988
+==========  ======================  ==================================

0 notes on commit 92241e2

Please sign in to comment.
Something went wrong with that request. Please try again.