Changeset 145
- Timestamp:
- 07/17/05 10:15:26 (3 years ago)
- Files:
-
- django/trunk/docs/templates.txt (modified) (25 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/trunk/docs/templates.txt
r112 r145 26 26 27 27 {% extends "base_generic" %} 28 28 29 29 {% block title %}{{ section.title }}{% endblock %} 30 30 31 31 {% block content %} 32 32 <h1>{{ section.title }}</h1> 33 33 34 34 {% for story in story_list %} 35 35 <h2> … … 48 48 encounters a variable, it evaluates that variable and replaces the variable with 49 49 the result. Many variables will be structures with named attributes; you can 50 "drill down" into these structures with dots (``.``), so in the above example 50 "drill down" into these structures with dots (``.``), so in the above example 51 51 ``{{ section.title }}`` will be replaced with the ``title`` attribute of the 52 52 ``section`` object. … … 58 58 are available in a given template. 59 59 60 Variables may be modified before being displayed by **filters**. 60 Variables may be modified before being displayed by **filters**. 61 61 62 62 What's a filter? … … 69 69 We use the pipe character to apply filters to emphasize the analogy with filters 70 70 on a water pipe: text enters one side, has some operation performed on it, and 71 "flows" out the other side. Filters may be "chained"; the output of one filter 72 applied to the next: ``{{ text|escape|linebreaks }}`` is a common idiom for 71 "flows" out the other side. Filters may be "chained"; the output of one filter 72 applied to the next: ``{{ text|escape|linebreaks }}`` is a common idiom for 73 73 escaping text contents and then converting line breaks to ``<p>`` tags. 74 74 … … 105 105 <title>{% block title %}My Amazing Site{% endblock %}</title> 106 106 </head> 107 107 108 108 <body> 109 109 <div id="sidebar"> … … 115 115 {% endblock %} 116 116 </div> 117 117 118 118 <div id="content"> 119 119 {% block content %}{% endblock %} 120 120 </div> 121 121 </body> 122 122 123 123 This template, which we'll call ``base.html`` defines a simple HTML skeleton 124 124 document that you might use for a simple two-column page. This template 125 won't actually be used directly on any pages, but other "child" templates will 126 extend it and fill in the empty blocks with content. 127 128 I've used the ``{% block %}`` tag to define the three blocks that child templates 129 will fill in. All that the ``block`` tag does is to signal to the template engine 125 won't actually be used directly on any pages, but other "child" templates will 126 extend it and fill in the empty blocks with content. 127 128 I've used the ``{% block %}`` tag to define the three blocks that child templates 129 will fill in. All that the ``block`` tag does is to signal to the template engine 130 130 that a child template may override those portions of the template. 131 131 … … 133 133 134 134 {% extends "base" %} 135 135 136 136 {% block title %}My Amazing Blog{% endblock %} 137 137 138 138 {% block content %} 139 139 140 140 {% for entry in blog_entries %} <h2>{{ entry.title }}</h2> <p>{{ entry.body 141 141 }}</p> {% endfor %} 142 142 143 143 {% endblock %} 144 144 145 145 The ``{% extends %}`` tag is the key here; it tells the template engine that 146 146 this template "extends" another template. When this template is evaluated, … … 160 160 <title>My Amazing Blog</title> 161 161 </head> 162 162 163 163 <body> 164 164 <div id="sidebar"> … … 168 168 </ul> 169 169 </div> 170 170 171 171 <div id="content"> 172 172 <h2>Entry one</h2> 173 173 <p>This is my first entry.</p> 174 174 175 175 <h2>Entry two</h2> 176 176 <p>This is my second entry.</p> … … 189 189 190 190 * More ``{% block %}`` tags in your base templates are better. Remember, 191 child templates do not have to define all parent blocks, so you can 191 child templates do not have to define all parent blocks, so you can 192 192 fill in reasonable defaults in a number of blocks, then only define 193 193 the ones you need later on. 194 195 * If you find yourself reproducing the same content in a number of 196 documents, it probably means you should move that content to a 194 195 * If you find yourself reproducing the same content in a number of 196 documents, it probably means you should move that content to a 197 197 new ``{% block %}`` in a parent template. 198 198 199 199 * We often prefer to use three-level inheritance: a single base template 200 200 for the entire site, a set of mid-level templates for each section of 201 201 the site, and then the individual templates for each page. This 202 maximizes code reuse, and makes it easier to add items to shared 202 maximizes code reuse, and makes it easier to add items to shared 203 203 content areas (like section-wide navigation). 204 204 205 205 * If you need to get the content of the block from the parent template, 206 206 the ``{{ block.super }}`` variable will do the trick. This is useful 207 if you want to add to the contents of a parent block instead of 207 if you want to add to the contents of a parent block instead of 208 208 completely overriding it. 209 209 210 210 Using the built-in reference 211 211 ============================ … … 248 248 249 249 {% load comments %} 250 250 251 251 {% comment_form for blogs.entries entry.id with is_public yes %} 252 252 253 253 In the above, the ``load`` tag loads the ``comments`` tag library, which then 254 254 makes the ``comment_form`` tag available for use. Consult the documentation … … 269 269 Define a block that can be overridden by child templates. See `Template 270 270 inheritance`_ for more information. 271 271 272 272 ``comment`` 273 273 Ignore everything between ``{% comment %}`` and ``{% endcomment %}`` 274 274 275 275 ``cycle`` 276 276 Cycle among the given strings each time this tag is encountered. 277 277 278 278 Within a loop, cycles among the given strings each time through 279 279 the loop:: 280 280 281 281 {% for o in some_list %} 282 282 <tr class="{% cycle row1,row2 %}"> … … 284 284 </tr> 285 285 {% endfor %} 286 286 287 287 Outside of a loop, give the values a unique name the first time you call it, 288 288 then use that name each successive time through:: 289 289 290 290 <tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr> 291 291 <tr class="{% cycle rowcolors %}">...</tr> 292 292 <tr class="{% cycle rowcolors %}">...</tr> 293 293 294 294 You can use any number of values, separated by commas. Make sure not to put 295 295 spaces between the values -- only commas. 296 296 297 297 ``debug`` 298 298 Output a whole load of debugging information, including the current context and 299 299 imported modules. 300 300 301 301 ``extends`` 302 302 Signal that this template extends a parent template. 303 303 304 304 This tag may be used in two ways: ``{% extends "base" %}`` (with quotes) uses 305 305 the literal value "base" as the name of the parent template to extend, or ``{% 306 306 extends variable %}`` uses the value of ``variable`` as the name of the parent 307 307 template to extend. 308 308 309 309 See `Template inheritance`_ for more information. 310 310 311 311 ``filter`` 312 Filter the contents of the blogthrough variable filters.313 312 Filter the contents of the variable through variable filters. 313 314 314 Filters can also be piped through each other, and they can have arguments -- 315 315 just like in variable syntax. 316 316 317 317 Sample usage:: 318 318 319 319 {% filter escape|lower %} 320 320 This text will be HTML-escaped, and will appear in all lowercase. 321 321 {% endfilter %} 322 322 323 323 ``firstof`` 324 324 Outputs the first variable passed that is not False. Outputs nothing if all the 325 325 passed variables are False. 326 326 327 327 Sample usage:: 328 328 329 329 {% firstof var1 var2 var3 %} 330 330 331 331 This is equivalent to:: 332 332 333 333 {% if var1 %} 334 334 {{ var1 }} … … 338 338 {{ var3 }} 339 339 {% endif %}{% endif %}{% endif %} 340 340 341 341 but obviously much cleaner! 342 342 343 343 ``for`` 344 344 Loop over each item in an array. For example, to display a list of athletes 345 345 given ``athlete_list``:: 346 346 347 347 <ul> 348 348 {% for athlete in athlete_list %} … … 350 350 {% endfor %} 351 351 </ul> 352 352 353 353 You can also loop over a list in reverse by using ``{% for obj in list reversed %}``. 354 354 355 355 The for loop sets a number of variables available within the loop: 356 356 357 357 ========================== ================================================ 358 358 Variable Description … … 365 365 current one 366 366 ========================== ================================================ 367 367 368 368 ``if`` 369 369 The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e. 370 370 exists, is not empty, and is not a false boolean value) the contents of the 371 371 block are output:: 372 372 373 373 {% if athlete_list %} 374 374 Number of athletes: {{ athlete_list|count }} … … 376 376 No athletes. 377 377 {% endif %} 378 378 379 379 In the above, if ``athlete_list`` is not empty, the number of athletes will be 380 380 displayed by the ``{{ athlete_list|count }}`` variable. 381 381 382 382 As you can see, the ``if`` tag can take an option ``{% else %}`` clause that 383 383 will be displayed if the test fails. 384 384 385 385 ``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate 386 386 a given variable:: 387 387 388 388 {% if not athlete_list %} 389 389 There are no athletes. 390 390 {% endif %} 391 391 392 392 {% if athlete_list or coach_list %} 393 393 There are some athletes or some coaches. 394 394 {% endif %} 395 395 396 396 {% if not athlete_list or coach_list %} 397 There are no athletes or there are some coaches (OK, so 398 writing English translations of boolean logic sounds 397 There are no athletes or there are some coaches (OK, so 398 writing English translations of boolean logic sounds 399 399 stupid; it's not my fault). 400 400 {% endif %} 401 402 For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if`` 401 402 For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if`` 403 403 tags instead:: 404 404 405 405 {% if athlete_list %} 406 406 {% if coach_list %} … … 409 409 {% endif %} 410 410 {% endif %} 411 411 412 412 ``ifchanged`` 413 413 Check if a value has changed from the last iteration of a loop. 414 414 415 415 The 'ifchanged' block tag is used within a loop. It checks its own rendered 416 416 contents against its previous state and only displays its content if the value 417 417 has changed:: 418 418 419 419 <h1>Archive for {{ year }}</h1> 420 420 421 421 {% for date in days %} 422 422 {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %} 423 423 <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a> 424 424 {% endfor %} 425 425 426 426 ``ifnotequal`` 427 427 Output the contents of the block if the two arguments do not equal each other. 428 428 429 429 Example:: 430 430 431 431 {% ifnotequal user.id_ comment.user_id %} 432 432 ... 433 433 {% endifnotequal %} 434 434 435 435 ``load`` 436 436 Load a custom template tag set. 437 437 438 438 See `Custom tag and filter libraries`_ for more information. 439 439 440 440 ``now`` 441 441 Display the date, formatted according to the given string. 442 442 443 443 Uses the same format as PHP's ``date()`` function; see http://php.net/date 444 444 for all the possible values. 445 445 446 446 Sample usage:: 447 447 448 448 It is {% now "jS F Y H:i" %} 449 449 450 450 ``regroup`` 451 451 Regroup a list of alike objects by a common attribute. 452 452 453 453 This complex tag is best illustrated by use of an example: say that ``people`` 454 454 is a list of ``Person`` objects that have ``first_name``, ``last_name``, and 455 455 ``gender`` attributes, and you'd like to display a list that looks like: 456 456 457 457 * Male: 458 458 * George Bush … … 463 463 * Unknown: 464 464 * Janet Reno 465 465 466 466 The following snippet of template code would accomplish this dubious task:: 467 467 468 468 {% regroup people by gender as grouped %} 469 469 <ul> … … 477 477 {% endfor %} 478 478 </ul> 479 479 480 480 As you can see, ``{% regroup %}`` populates a variable with a list of objects 481 481 with ``grouper`` and ``list`` attributes. ``grouper`` contains the item that … … 483 483 ``grouper``. In this case, ``grouper`` would be ``Male``, ``Female`` and 484 484 ``Unknown``, and ``list`` is the list of people with those genders. 485 485 486 486 Note that ``{% regroup %}`` does not work when the list to be grouped is not 487 487 sorted by the key you are grouping by! This means that if your list of people 488 488 was not sorted by gender, you'd need to make sure it is sorted before using it, 489 489 i.e.:: 490 490 491 491 {% regroup people|dictsort:"gender" by gender as grouped %} 492 492 493 493 ``ssi`` 494 494 Output the contents of a given file into the page. 495 495 496 496 Like a simple "include" tag, the ``ssi`` tag includes the contents 497 497 of another file -- which must be specified using an absolute page -- 498 498 in the current page:: 499 499 500 500 {% ssi /home/html/ljworld.com/includes/right_generic.html %} 501 501 502 502 If the optional "parsed" parameter is given, the contents of the included 503 503 file are evaluated as template code, with the current context:: 504 504 505 505 {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %} 506 506 507 507 ``templatetag`` 508 508 Output one of the bits used to compose template tags. 509 509 510 510 Since the template system has no concept of "escaping", to display one of the 511 511 bits used in template tags, you must use the ``{% templatetag %}`` tag. 512 512 513 513 The argument tells which template bit to output: 514 514 515 515 ================== ======= 516 516 Argument Outputs … … 521 521 ``closevariable`` ``}}`` 522 522 ================== ======= 523 523 524 524 ``widthratio`` 525 525 For creating bar charts and such, this tag calculates the ratio of a given value 526 526 to a maximum value, and then applies that ratio to a constant. 527 527 528 528 For example:: 529 529 530 530 <img src='bar.gif' height='10' width='{% widthratio this_value max_value 100 %}' /> 531 531 532 532 Above, if ``this_value`` is 175 and ``max_value`` is 200, the the image in the 533 533 above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5 … … 539 539 ``add`` 540 540 Adds the arg to the value 541 541 542 542 ``addslashes`` 543 543 Adds slashes - useful for passing strings to JavaScript, for example. 544 544 545 545 ``capfirst`` 546 546 Capitalizes the first character of the value 547 547 548 548 ``center`` 549 549 Centers the value in a field of a given width 550 550 551 551 ``cut`` 552 552 Removes all values of arg from the given string 553 553 554 554 ``date`` 555 555 Formats a date according to the given format (same as the ``now`` tag) 556 556 557 557 ``default`` 558 558 If value is unavailable, use given default 559 559 560 560 ``dictsort`` 561 561 Takes a list of dicts, returns that list sorted by the property given in the 562 562 argument. 563 563 564 564 ``dictsortreversed`` 565 565 Takes a list of dicts, returns that list sorted in reverse order by the property 566 566 given in the argument. 567 567 568 568 ``divisibleby`` 569 569 Returns true if the value is divisible by the argument 570 570 571 571 ``escape`` 572 572 Escapes a string's HTML 573 573 574 574 ``filesizeformat`` 575 575 Format the value like a 'human-readable' file size (i.e. 13 KB, 4.1 MB, 102 576 576 bytes, etc). 577 577 578 578 ``first`` 579 579 Returns the first item in a list 580 580 581 581 ``fix_ampersands`` 582 582 Replaces ampersands with ``&`` entities 583 583 584 584 ``floatformat`` 585 585 Displays a floating point number as 34.2 (with one decimal places) - but 586 586 only if there's a point to be displayed 587 587 588 588 ``get_digit`` 589 589 Given a whole number, returns the requested digit of it, where 1 is the … … 591 591 original value for invalid input (if input or argument is not an integer, 592 592 or if argument is less than 1). Otherwise, output is always an integer. 593 593 594 594 ``join`` 595 595 Joins a list with a string, like Python's ``str.join(list)`` 596 596 597 597 ``length`` 598 598 Returns the length of the value - useful for lists 599 599 600 600 ``length_is`` 601 601 Returns a boolean of whether the value's length is the argument 602 602 603 603 ``linebreaks`` 604 604 Converts newlines into <p> and <br />s 605 605 606 606 ``linebreaksbr`` 607 607 Converts newlines into <br />s 608 608 609 609 ``linenumbers`` 610 610 Displays text with line numbers 611 611 612 612 ``ljust`` 613 613 Left-aligns the value in a field of a given width 614 614 615 615 **Argument:** field size 616 616 617 617 ``lower`` 618 618 Converts a string into all lowercase 619 619 620 620 ``make_list`` 621 621 Returns the value turned into a list. For an integer, it's a list of 622 622 digits. For a string, it's a list of characters. 623 623 624 624 ``phone2numeric`` 625 625 Takes a phone number and converts it in to its numerical equivalent 626 626 627 627 ``pluralize`` 628 628 Returns 's' if the value is not 1, for '1 vote' vs. '2 votes' 629 629 630 630 ``pprint`` 631 631 A wrapper around pprint.pprint -- for debugging, really 632 632 633 633 ``random`` 634 634 Returns a random item from the list 635 635 636 636 ``removetags`` 637 637 Removes a space separated list of [X]HTML tags from the output 638 638 639 639 ``rjust`` 640 640 Right-aligns the value in a field of a given width 641 641 642 642 **Argument:** field size 643 643 644 644 ``slice`` 645 645 Returns a slice of the list. 646 646 647 647 Uses the same syntax as Python's list slicing; see 648 648 http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice 649 649 for an introduction. 650 650 651 651 ``slugify`` 652 652 Converts to lowercase, removes non-alpha chars and converts spaces to hyphens 653 653 654 654 ``stringformat`` 655 655 Formats the variable according to the argument, a string formatting specifier. 656 656 This specifier uses Python string formating syntax, with the exception that 657 657 the leading "%" is dropped. 658 658 659 659 See http://docs.python.org/lib/typesseq-strings.html for documentation 660 660 of Python string formatting 661 661 662 662 ``striptags`` 663 663 Strips all [X]HTML tags 664 664 665 665 ``time`` 666 666 Formats a time according to the given format (same as the ``now`` tag). 667 667 668 668 ``timesince`` 669 669 Formats a date as the time since that date (i.e. "4 days, 6 hours") 670 670 671 671 ``title`` 672 672 Converts a string into titlecase 673 673 674 674 ``truncatewords`` 675 675 Truncates a string after a certain number of words 676 676 677 677 **Argument:** Number of words to truncate after 678 678 679 679 ``unordered_list`` 680 680 Recursively takes a self-nested list and returns an HTML unordered list -- 681 681 WITHOUT opening and closing <ul> tags. 682 682 683 683 The list is assumed to be in the proper format. For example, if ``var`` contains 684 684 ``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``, 685 685 then ``{{ var|unordered_list }}`` would return:: 686 686 687 687 <li>States 688 688 <ul> … … 696 696 </ul> 697 697 </li> 698 698 699 699 ``upper`` 700 700 Converts a string into all uppercase 701 701 702 702 ``urlencode`` 703 703 Escapes a value for use in a URL 704 704 705 705 ``urlize`` 706 706 Converts URLs in plain text into clickable links 707 707 708 708 ``urlizetrunc`` 709 709 Converts URLs into clickable links, truncating URLs to the given character limit 710 710 711 711 **Argument:** Length to truncate URLs to. 712 712 713 713 ``wordcount`` 714 714 Returns the number of words 715 715 716 716 ``wordwrap`` 717 717 Wraps words at specified line length 718 718 719 719 **Argument:** number of words to wrap the text at. 720 720 721 721 ``yesno`` 722 722 Given a string mapping values for true, false and (optionally) None, 723 723 returns one of those strings according to the value: 724 724 725 725 ========== ====================== ================================== 726 726 Value Argument Outputs
