1############# 2Template Tags 3############# 4 5.. module:: cms.templatetags.cms_tags 6 7***************** 8CMS template tags 9***************** 10 11.. highlightlang:: html+django 12 13To use any of the following template tags you first need to load them at the 14top of your template:: 15 16 {% load cms_tags %} 17 18 19Placeholders 20============ 21 22.. templatetag:: placeholder 23 24placeholder 25----------- 26 27The ``placeholder`` template tag defines a placeholder on a page. All 28placeholders in a template will be auto-detected and can be filled with 29plugins when editing a page that is using said template. When rendering, the 30content of these plugins will appear where the ``placeholder`` tag was. 31 32Example:: 33 34 {% placeholder "content" %} 35 36.. image:: /reference/images/placeholder.png 37 :alt: a placeholder named 'content' 38 :align: center 39 40If you want additional content to be displayed in case the placeholder is 41empty, use the ``or`` argument and an additional ``{% endplaceholder %}`` 42closing tag. Everything between ``{% placeholder "..." or %}`` and ``{% 43endplaceholder %}`` is rendered in the event that the placeholder has no plugins or 44the plugins do not generate any output. 45 46Example:: 47 48 {% placeholder "content" or %}There is no content.{% endplaceholder %} 49 50If you want to add extra variables to the context of the placeholder, you 51should use Django's :ttag:`with` tag. For instance, if you want to re-size images 52from your templates according to a context variable called ``width``, you can 53pass it as follows:: 54 55 {% with 320 as width %}{% placeholder "content" %}{% endwith %} 56 57If you want the placeholder to inherit the content of a placeholder with the 58same name on parent pages, simply pass the ``inherit`` argument:: 59 60 {% placeholder "content" inherit %} 61 62This will walk up the page tree up until the root page and will show the first 63placeholder it can find with content. 64 65It's also possible to combine this with the ``or`` argument to show an 66ultimate fallback if the placeholder and none of the placeholders on parent 67pages have plugins that generate content:: 68 69 {% placeholder "content" inherit or %}There is no spoon.{% endplaceholder %} 70 71See also the :setting:`CMS_PLACEHOLDER_CONF` setting where you can also add extra 72context variables and change some other placeholder behaviour. 73 74.. important:: 75 76 ``{% placeholder %}`` will only work inside the template's ``<body>``. 77 78 79.. templatetag:: static_placeholder 80 81static_placeholder 82------------------ 83 84The ``{% static_placeholder %}`` template tag can be used anywhere in a template element after 85the ``{% cms_toolbar %}`` tag. A static placeholder instance is not bound to any particular page 86or model - in other words, everywhere it appears, a static placeholder will hold exactly the same 87content. 88 89The ``{% static_placeholder %}`` tag is normally used to display the same content on multiple 90locations or inside of apphooks or other third party apps. 91 92Otherwise, a static placeholder behaves like a "normal" placeholder, to which plugins can be added. 93 94A static placeholder needs to be published to show up on live pages, and requires a name. 95 96Example:: 97 98 {% load cms_tags %} 99 100 {% static_placeholder "footer" %} 101 102.. image:: /reference/images/static-placeholder.png 103 :alt: a static placeholder 104 :align: center 105 106.. note:: 107 108 To reduce clutter in the interface, the plugins in static placeholders are hidden by default. 109 Click or tap on the name of the static placeholder to reveal/hide them. 110 111If you want additional content to be displayed in case the static placeholder is 112empty, use the ``or`` argument and an additional ``{% endstatic_placeholder %}`` 113closing tag. Everything between ``{% static_placeholder "..." or %}`` and ``{% 114endstatic_placeholder %}`` is rendered in the event that the placeholder has no plugins or 115the plugins do not generate any output. 116 117Example:: 118 119 {% static_placeholder "footer" or %}There is no content.{% endstatic_placeholder %} 120 121By default, a static placeholder applies to *all* sites in a project. 122 123If you want to make your static placeholder site-specific, so that different sites can have their 124own content in it, you can add the flag ``site`` to the template tag to achieve this. 125 126Example:: 127 128 {% static_placeholder "footer" site or %}There is no content.{% endstatic_placeholder %} 129 130Note that the `Django "sites" framework <https://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_ *is* required and 131``SITE_ID`` *must* be set in ``settings.py`` for this (not to mention other aspects of django CMS) to work correctly. 132 133.. important:: 134 135 ``{% static_placeholder %}`` will only work inside the template's ``<body>``. 136 137 138.. templatetag:: render_placeholder 139 140render_placeholder 141================== 142 143``{% render_placeholder %}`` is used if you have a PlaceholderField in your own model and want 144to render it in the template. 145 146The :ttag:`render_placeholder` tag takes the following parameters: 147 148* :class:`~cms.models.fields.PlaceholderField` instance 149* ``width`` parameter for context sensitive plugins (optional) 150* ``language`` keyword plus ``language-code`` string to render content in the 151 specified language (optional) 152* ``as`` keyword followed by ``varname`` (optional): the template tag output can 153 be saved as a context variable for later use. 154 155 156The following example renders the ``my_placeholder`` field from the ``mymodel_instance`` and will 157render only the English (``en``) plugins: 158 159.. code-block:: html+django 160 161 {% load cms_tags %} 162 163 {% render_placeholder mymodel_instance.my_placeholder language 'en' %} 164 165.. versionadded:: 3.0.2 166 This template tag supports the ``as`` argument. With this you can assign the result 167 of the template tag to a new variable that you can use elsewhere in the template. 168 169 Example:: 170 171 {% render_placeholder mymodel_instance.my_placeholder as placeholder_content %} 172 <p>{{ placeholder_content }}</p> 173 174 When used in this manner, the placeholder will not be displayed for 175 editing when the CMS is in edit mode. 176 177.. templatetag:: render_uncached_placeholder 178 179render_uncached_placeholder 180=========================== 181 182The same as :ttag:`render_placeholder`, but the placeholder contents will not be 183cached or taken from the cache. 184 185Arguments: 186 187* :class:`~cms.models.fields.PlaceholderField` instance 188* ``width`` parameter for context sensitive plugins (optional) 189* ``language`` keyword plus ``language-code`` string to render content in the 190 specified language (optional) 191* ``as`` keyword followed by ``varname`` (optional): the template tag output can 192 be saved as a context variable for later use. 193 194Example:: 195 196 {% render_uncached_placeholder mymodel_instance.my_placeholder language 'en' %} 197 198 199.. templatetag:: show_placeholder 200 201show_placeholder 202================ 203 204Displays a specific placeholder from a given page. This is useful if you want 205to have some more or less static content that is shared among many pages, such 206as a footer. 207 208Arguments: 209 210* ``placeholder_name`` 211* ``page_lookup`` (see `page_lookup`_ for more information) 212* ``language`` (optional) 213* ``site`` (optional) 214 215Examples:: 216 217 {% show_placeholder "footer" "footer_container_page" %} 218 {% show_placeholder "content" request.current_page.parent_id %} 219 {% show_placeholder "teaser" request.current_page.get_root %} 220 221 222.. templatetag:: show_uncached_placeholder 223 224show_uncached_placeholder 225========================= 226 227The same as :ttag:`show_placeholder`, but the placeholder contents will not be 228cached or taken from the cache. 229 230Arguments: 231 232- ``placeholder_name`` 233- ``page_lookup`` (see `page_lookup`_ for more information) 234- ``language`` (optional) 235- ``site`` (optional) 236 237Example:: 238 239 {% show_uncached_placeholder "footer" "footer_container_page" %} 240 241 242.. templatetag:: page_lookup 243 244page_lookup 245=========== 246 247The ``page_lookup`` argument, passed to several template tags to retrieve a 248page, can be of any of the following types: 249 250* :class:`str`: interpreted as the ``reverse_id`` field of the desired page, which 251 can be set in the "Advanced" section when editing a page. 252* :class:`int`: interpreted as the primary key (``pk`` field) of the desired page 253* :class:`dict`: a dictionary containing keyword arguments to find the desired page 254 (for instance: ``{'pk': 1}``) 255* :class:`~cms.models.Page`: you can also pass a page object directly, in which case there will 256 be no database lookup. 257 258If you know the exact page you are referring to, it is a good idea to use a 259``reverse_id`` (a string used to uniquely name a page) rather than a 260hard-coded numeric ID in your template. For example, you might have a help 261page that you want to link to or display parts of on all pages. To do this, 262you would first open the help page in the admin interface and enter an ID 263(such as ``help``) under the 'Advanced' tab of the form. Then you could use 264that ``reverse_id`` with the appropriate template tags:: 265 266 {% show_placeholder "right-column" "help" %} 267 <a href="{% page_url "help" %}">Help page</a> 268 269If you are referring to a page `relative` to the current page, you'll probably 270have to use a numeric page ID or a page object. For instance, if you want the 271content of the parent page to display on the current page, you can use:: 272 273 {% show_placeholder "content" request.current_page.parent_id %} 274 275Or, suppose you have a placeholder called ``teaser`` on a page that, unless a 276content editor has filled it with content specific to the current page, should 277inherit the content of its root-level ancestor:: 278 279 {% placeholder "teaser" or %} 280 {% show_placeholder "teaser" request.current_page.get_root %} 281 {% endplaceholder %} 282 283 284.. templatetag:: page_url 285 286 287page_url 288======== 289 290Displays the URL of a page in the current language. 291 292Arguments: 293 294- ``page_lookup`` (see `page_lookup`_ for more information) 295- ``language`` (optional) 296- ``site`` (optional) 297- ``as var_name`` (version 3.0 or later, optional; page_url can now be used to assign the resulting 298 URL to a context variable ``var_name``) 299 300 301Example:: 302 303 <a href="{% page_url "help" %}">Help page</a> 304 <a href="{% page_url request.current_page.parent %}">Parent page</a> 305 306If a matching page isn't found and :setting:`django:DEBUG` is ``True``, an 307exception will be raised. However, if :setting:`django:DEBUG` is ``False``, an 308exception will not be raised. 309 310.. versionadded:: 3.0 311 312 page_url now supports the ``as`` argument. When used this way, the tag 313 emits nothing, but sets a variable in the context with the specified name 314 to the resulting value. 315 316 When using the ``as`` argument PageNotFound exceptions are always 317 suppressed, regardless of the setting of :setting:`django:DEBUG` and the 318 tag will simply emit an empty string in these cases. 319 320Example:: 321 322 {# Emit a 'canonical' tag when the page is displayed on an alternate url #} 323 {% page_url request.current_page as current_url %}{% if current_url and current_url != request.get_full_path %}<link rel="canonical" href="{% page_url request.current_page %}">{% endif %} 324 325 326.. templatetag:: page_attribute 327 328page_attribute 329============== 330 331This template tag is used to display an attribute of the current page in the 332current language. 333 334Arguments: 335 336- ``attribute_name`` 337- ``page_lookup`` (optional; see `page_lookup`_ for more 338 information) 339 340Possible values for ``attribute_name`` are: ``"title"``, ``"menu_title"``, 341``"page_title"``, ``"slug"``, ``"meta_description"``, ``"changed_date"``, ``"changed_by"`` 342(note that you can also supply that argument without quotes, but this is 343deprecated because the argument might also be a template variable). 344 345Example:: 346 347 {% page_attribute "page_title" %} 348 349If you supply the optional ``page_lookup`` argument, you will get the page 350attribute from the page found by that argument. 351 352Example:: 353 354 {% page_attribute "page_title" "my_page_reverse_id" %} 355 {% page_attribute "page_title" request.current_page.parent_id %} 356 {% page_attribute "slug" request.current_page.get_root %} 357 358.. versionadded:: 2.3.2 359 This template tag supports the ``as`` argument. With this you can assign the result 360 of the template tag to a new variable that you can use elsewhere in the template. 361 362 Example:: 363 364 {% page_attribute "page_title" as title %} 365 <title>{{ title }}</title> 366 367 It even can be used in combination with the ``page_lookup`` argument. 368 369 Example:: 370 371 {% page_attribute "page_title" "my_page_reverse_id" as title %} 372 <a href="/mypage/">{{ title }}</a> 373 374.. templatetag:: render_plugin 375.. versionadded:: 2.4 376 377render_plugin 378============= 379 380This template tag is used to render child plugins of the current plugin and should be used inside plugin templates. 381 382Arguments: 383 384- ``plugin`` 385 386Plugin needs to be an instance of a plugin model. 387 388Example:: 389 390 {% load cms_tags %} 391 <div class="multicolumn"> 392 {% for plugin in instance.child_plugin_instances %} 393 <div style="width: {{ plugin.width }}00px;"> 394 {% render_plugin plugin %} 395 </div> 396 {% endfor %} 397 </div> 398 399Normally the children of plugins can be accessed via the ``child_plugins`` attribute of plugins. 400Plugins need the ``allow_children`` attribute to set to `True` for this to be enabled. 401 402.. versionadded:: 3.0 403.. templatetag:: render_plugin_block 404 405render_plugin_block 406=================== 407 408This template tag acts like the template tag ``render_model_block`` but with a 409plugin instead of a model as its target. This is used to link from a block of 410markup to a plugin's change form in edit/preview mode. 411 412This is useful for user interfaces that have some plugins hidden from display 413in edit/preview mode, but the CMS author needs to expose a way to edit them. 414It is also useful for just making duplicate or alternate means of triggering 415the change form for a plugin. 416 417This would typically be used inside a parent-plugin’s render template. In this 418example code below, there is a parent container plugin which renders a list of 419child plugins inside a navigation block, then the actual plugin contents inside a 420``DIV.contentgroup-items`` block. In this example, the navigation block is always shown, 421but the items are only shown once the corresponding navigation element is 422clicked. Adding this ``render_plugin_block`` makes it significantly more intuitive 423to edit a child plugin's content, by double-clicking its navigation item in edit mode. 424 425Arguments: 426 427- ``plugin`` 428 429Example:: 430 431 {% load cms_tags l10n %} 432 433 {% block section_content %} 434 <div class="contentgroup-container"> 435 <nav class="contentgroup"> 436 <div class="inner"> 437 <ul class="contentgroup-items">{% for child in children %} 438 {% if child.enabled %} 439 <li class="item{{ forloop.counter0|unlocalize }}"> 440 {% render_plugin_block child %} 441 <a href="#item{{ child.id|unlocalize }}">{{ child.title|safe }}</a> 442 {% endrender_plugin_block %} 443 </li>{% endif %} 444 {% endfor %} 445 </ul> 446 </div> 447 </nav> 448 449 <div class="contentgroup-items">{% for child in children %} 450 <div class="contentgroup-item item{{ child.id|unlocalize }}{% if not forloop.counter0 %} active{% endif %}"> 451 {% render_plugin child %} 452 </div>{% endfor %} 453 </div> 454 </div> 455 {% endblock %} 456 457.. templatetag:: render_model 458.. versionadded:: 3.0 459 460render_model 461============ 462 463``render_model`` is the way to add frontend editing to any Django model. 464It both renders the content of the given attribute of the model instance and 465makes it clickable to edit the related model. 466 467If the toolbar is not enabled, the value of the attribute is rendered in the 468template without further action. 469 470If the toolbar is enabled, click to call frontend editing code is added. 471 472By using this template tag you can show and edit page titles as well as fields in 473standard django models, see :ref:`frontend-editable-fields` for examples and 474further documentation. 475 476Example: 477 478.. code-block:: html+django 479 480 <h1>{% render_model my_model "title" "title,abstract" %}</h1> 481 482This will render to: 483 484.. code-block:: html+django 485 486 <!-- The content of the H1 is the active area that triggers the frontend editor --> 487 <h1><cms-plugin class="cms-plugin cms-plugin-myapp-mymodel-title-1">{{ my_model.title }}</cms-plugin></h1> 488 489**Arguments:** 490 491* ``instance``: instance of your model in the template 492* ``attribute``: the name of the attribute you want to show in the template; it 493 can be a context variable name; it's possible to target field, property or 494 callable for the specified model; when used on a page object this argument 495 accepts the special ``titles`` value which will show the page **title** 496 field, while allowing editing **title**, **menu title** and **page title** 497 fields in the same form; 498* ``edit_fields`` (optional): a comma separated list of fields editable in the 499 popup editor; when template tag is used on a page object this argument 500 accepts the special ``changelist`` value which allows editing the pages 501 **changelist** (items list); 502* ``language`` (optional): the admin language tab to be linked. Useful only for 503 `django-hvad`_ enabled models. 504* ``filters`` (optional): a string containing chained filters to apply to the 505 output content; works the same way as :ttag:`django:filter` template tag; 506* ``view_url`` (optional): the name of a URL that will be reversed using the 507 instance ``pk`` and the ``language`` as arguments; 508* ``view_method`` (optional): a method name that will return a URL to a view; 509 the method must accept ``request`` as first parameter. 510* ``varname`` (optional): the template tag output can be saved as a context 511 variable for later use. 512 513.. note:: 514 515 By default this template tag escapes the content of the rendered 516 model attribute. This helps prevent a range of security vulnerabilities 517 stemming from HTML, JavaScript, and CSS Code Injection. 518 519 To change this behaviour, the project administrator should carefully review 520 each use of this template tag and ensure that all content which is rendered 521 to a page using this template tag is cleansed of any potentially harmful 522 HTML markup, CSS styles or JavaScript. 523 524 Once the administrator is satisfied that the content is 525 clean, he or she can add the "safe" filter parameter to the template tag 526 if the content should be rendered without escaping. 527 528.. warning:: 529 530 ``render_model`` is only partially compatible with django-hvad: using 531 it with hvad-translated fields 532 (say {% render_model object 'translated_field' %} return error if the 533 hvad-enabled object does not exists in the current language. 534 As a workaround ``render_model_icon`` can be used instead. 535 536 537.. templatetag:: render_model_block 538.. versionadded:: 3.0 539 540render_model_block 541================== 542 543``render_model_block`` is the block-level equivalent of ``render_model``: 544 545.. code-block:: html+django 546 547 {% render_model_block my_model %} 548 <h1>{{ instance.title }}</h1> 549 <div class="body"> 550 {{ instance.date|date:"d F Y" }} 551 {{ instance.text }} 552 </div> 553 {% endrender_model_block %} 554 555This will render to: 556 557.. code-block:: html+django 558 559 <!-- This whole block is the active area that triggers the frontend editor --> 560 <template class="cms-plugin cms-plugin-start cms-plugin-myapp-mymodel-1"></template> 561 <h1>{{ my_model.title }}</h1> 562 <div class="body"> 563 {{ my_model.date|date:"d F Y" }} 564 {{ my_model.text }} 565 </div> 566 <template class="cms-plugin cms-plugin-end cms-plugin-myapp-mymodel-1"></template> 567 568In the block the ``my_model`` is aliased as ``instance`` and every attribute and 569method is available; also template tags and filters are available in the block. 570 571.. warning:: 572 573 If the ``{% render_model_block %}`` contains template tags or template code that rely on or 574 manipulate context data that the ``{% render_model_block %}`` also makes use of, you may 575 experience some unexpected effects. Unless you are sure that such conflicts will not occur 576 it is advised to keep the code within a ``{% render_model_block %}`` as simple and short as 577 possible. 578 579**Arguments:** 580 581* ``instance``: instance of your model in the template 582* ``edit_fields`` (optional): a comma separated list of fields editable in the 583 popup editor; when template tag is used on a page object this argument 584 accepts the special ``changelist`` value which allows editing the pages 585 **changelist** (items list); 586* ``language`` (optional): the admin language tab to be linked. Useful only for 587 `django-hvad`_ enabled models. 588* ``view_url`` (optional): the name of a URL that will be reversed using the 589 instance ``pk`` and the ``language`` as arguments; 590* ``view_method`` (optional): a method name that will return a URL to a view; 591 the method must accept ``request`` as first parameter. 592* ``varname`` (optional): the template tag output can be saved as a context 593 variable for later use. 594 595.. note:: 596 597 By default this template tag escapes the content of the rendered 598 model attribute. This helps prevent a range of security vulnerabilities 599 stemming from HTML, JavaScript, and CSS Code Injection. 600 601 To change this behaviour, the project administrator should carefully review 602 each use of this template tag and ensure that all content which is rendered 603 to a page using this template tag is cleansed of any potentially harmful 604 HTML markup, CSS styles or JavaScript. 605 606 Once the administrator is satisfied that the content is 607 clean, he or she can add the "safe" filter parameter to the template tag 608 if the content should be rendered without escaping. 609 610 611.. templatetag:: render_model_icon 612.. versionadded:: 3.0 613 614 615render_model_icon 616================= 617 618``render_model_icon`` is intended for use where the relevant object attribute 619is not available for user interaction (for example, already has a link on it, 620think of a title in a list of items and the titles are linked to the object 621detail view); when in edit mode, it renders an **edit** icon, which will trigger 622the editing change form for the provided fields. 623 624 625.. code-block:: html+django 626 627 <h3><a href="{{ my_model.get_absolute_url }}">{{ my_model.title }}</a> {% render_model_icon my_model %}</h3> 628 629It will render to something like: 630 631.. code-block:: html+django 632 633 <h3> 634 <a href="{{ my_model.get_absolute_url }}">{{ my_model.title }}</a> 635 <template class="cms-plugin cms-plugin-start cms-plugin-myapp-mymodel-1 cms-render-model-icon"></template> 636 <!-- The image below is the active area that triggers the frontend editor --> 637 <img src="/static/cms/img/toolbar/render_model_placeholder.png"> 638 <template class="cms-plugin cms-plugin-end cms-plugin-myapp-mymodel-1 cms-render-model-icon"></template> 639 </h3> 640 641.. note:: 642 643 Icon and position can be customised via CSS by setting a background 644 to the ``.cms-render-model-icon img`` selector. 645 646**Arguments:** 647 648* ``instance``: instance of your model in the template 649* ``edit_fields`` (optional): a comma separated list of fields editable in the 650 popup editor; when template tag is used on a page object this argument 651 accepts the special ``changelist`` value which allows editing the pages 652 **changelist** (items list); 653* ``language`` (optional): the admin language tab to be linked. Useful only for 654 `django-hvad`_ enabled models. 655* ``view_url`` (optional): the name of a URL that will be reversed using the 656 instance ``pk`` and the ``language`` as arguments; 657* ``view_method`` (optional): a method name that will return a URL to a view; 658 the method must accept ``request`` as first parameter. 659* ``varname`` (optional): the template tag output can be saved as a context 660 variable for later use. 661 662.. note:: 663 664 By default this template tag escapes the content of the rendered 665 model attribute. This helps prevent a range of security vulnerabilities 666 stemming from HTML, JavaScript, and CSS Code Injection. 667 668 To change this behaviour, the project administrator should carefully review 669 each use of this template tag and ensure that all content which is rendered 670 to a page using this template tag is cleansed of any potentially harmful 671 HTML markup, CSS styles or JavaScript. 672 673 Once the administrator is satisfied that the content is 674 clean, he or she can add the "safe" filter parameter to the template tag 675 if the content should be rendered without escaping. 676 677 678.. templatetag:: render_model_add 679.. versionadded:: 3.0 680 681 682render_model_add 683================ 684 685``render_model_add`` is similar to ``render_model_icon`` but it will enable to 686create instances of the given instance class; when in edit mode, it renders an 687**add** icon, which will trigger the editing add form for the provided model. 688 689 690.. code-block:: html+django 691 692 <h3><a href="{{ my_model.get_absolute_url }}">{{ my_model.title }}</a> {% render_model_add my_model %}</h3> 693 694It will render to something like: 695 696.. code-block:: html+django 697 698 <h3> 699 <a href="{{ my_model.get_absolute_url }}">{{ my_model.title }}</a> 700 <template class="cms-plugin cms-plugin-start cms-plugin-myapp-mymodel-1 cms-render-model-add"></template> 701 <!-- The image below is the active area that triggers the frontend editor --> 702 <img src="/static/cms/img/toolbar/render_model_placeholder.png"> 703 <template class="cms-plugin cms-plugin-end cms-plugin-myapp-mymodel-1 cms-render-model-add"></template> 704 </h3> 705 706.. note:: 707 708 Icon and position can be customised via CSS by setting a background 709 to the ``.cms-render-model-add img`` selector. 710 711**Arguments:** 712 713* ``instance``: instance of your model, or model class to be added 714* ``edit_fields`` (optional): a comma separated list of fields editable in the 715 popup editor; 716* ``language`` (optional): the admin language tab to be linked. Useful only for 717 `django-hvad`_ enabled models. 718* ``view_url`` (optional): the name of a url that will be reversed using the 719 instance ``pk`` and the ``language`` as arguments; 720* ``view_method`` (optional): a method name that will return a URL to a view; 721 the method must accept ``request`` as first parameter. 722* ``varname`` (optional): the template tag output can be saved as a context 723 variable for later use. 724 725.. note:: 726 727 By default this template tag escapes the content of the rendered 728 model attribute. This helps prevent a range of security vulnerabilities 729 stemming from HTML, JavaScript, and CSS Code Injection. 730 731 To change this behaviour, the project administrator should carefully review 732 each use of this template tag and ensure that all content which is rendered 733 to a page using this template tag is cleansed of any potentially harmful 734 HTML markup, CSS styles or JavaScript. 735 736 Once the administrator is satisfied that the content is 737 clean, he or she can add the "safe" filter parameter to the template tag 738 if the content should be rendered without escaping. 739 740.. warning:: 741 742 If passing a class, instead of an instance, and using ``view_method``, 743 please bear in mind that the method will be called over an **empty instance** 744 of the class, so attributes are all empty, and the instance does not 745 exists on the database. 746 747 748.. _django-hvad: https://github.com/kristianoellegaard/django-hvad 749 750.. templatetag:: render_model_add_block 751.. versionadded:: 3.1 752 753render_model_add_block 754====================== 755 756``render_model_add_block`` is similar to ``render_model_add`` but instead of 757emitting an icon that is linked to the add model form in a modal dialog, it 758wraps arbitrary markup with the same "link". This allows the developer to create 759front-end editing experiences better suited to the project. 760 761All arguments are identical to ``render_model_add``, but the template tag is used 762in two parts to wrap the markup that should be wrapped. 763 764.. code-block:: html+django 765 766 {% render_model_add_block my_model_instance %}<div>New Object</div>{% endrender_model_add_block %} 767 768 769It will render to something like: 770 771.. code-block:: html+django 772 773 <template class="cms-plugin cms-plugin-start cms-plugin-myapp-mymodel-1 cms-render-model-add"></template> 774 <div>New Object</div> 775 <template class="cms-plugin cms-plugin-end cms-plugin-myapp-mymodel-1 cms-render-model-add"></template> 776 777 778.. warning:: 779 780 You **must** pass an *instance* of your model as instance parameter. The 781 instance passed could be an existing models instance, or one newly created 782 in your view/plugin. It does not even have to be saved, it is introspected 783 by the template tag to determine the desired model class. 784 785 786**Arguments:** 787 788* ``instance``: instance of your model in the template 789* ``edit_fields`` (optional): a comma separated list of fields editable in the 790 popup editor; 791* ``language`` (optional): the admin language tab to be linked. Useful only for 792 `django-hvad`_ enabled models. 793* ``view_url`` (optional): the name of a URL that will be reversed using the 794 instance ``pk`` and the ``language`` as arguments; 795* ``view_method`` (optional): a method name that will return a URL to a view; 796 the method must accept ``request`` as first parameter. 797* ``varname`` (optional): the template tag output can be saved as a context 798 variable for later use. 799 800.. _django-hvad: https://github.com/kristianoellegaard/django-hvad 801 802 803.. templatetag:: page_language_url 804 805 806page_language_url 807================= 808 809Returns the URL of the current page in an other language:: 810 811 {% page_language_url "de" %} 812 {% page_language_url "fr" %} 813 {% page_language_url "en" %} 814 815If the current URL has no CMS Page and is handled by a navigation extender and 816the URL changes based on the language, you will need to set a ``language_changer`` 817function with the ``set_language_changer`` function in ``menus.utils``. 818 819For more information, see :doc:`/topics/i18n`. 820 821 822.. templatetag:: language_chooser 823 824language_chooser 825================ 826 827The ``language_chooser`` template tag will display a language chooser for the 828current page. You can modify the template in ``menu/language_chooser.html`` or 829provide your own template if necessary. 830 831Example:: 832 833 {% language_chooser %} 834 835or with custom template:: 836 837 {% language_chooser "myapp/language_chooser.html" %} 838 839The language_chooser has three different modes in which it will display the 840languages you can choose from: "raw" (default), "native", "current" and "short". 841It can be passed as the last argument to the ``language_chooser tag`` as a string. 842In "raw" mode, the language will be displayed like its verbose name in the 843settings. In "native" mode the languages are displayed in their actual language 844(eg. German will be displayed "Deutsch", Japanese as "日本語" etc). In "current" 845mode the languages are translated into the current language the user is seeing 846the site in (eg. if the site is displayed in German, Japanese will be displayed 847as "Japanisch"). "Short" mode takes the language code (eg. "en") to display. 848 849If the current URL has no CMS Page and is handled by a navigation extender and 850the URL changes based on the language, you will need to set a ``language_changer`` 851function with the ``set_language_changer`` function in ``menus.utils``. 852 853For more information, see :doc:`/topics/i18n`. 854 855 856.. templatetag:: cms_toolbar 857 858********************* 859Toolbar template tags 860********************* 861 862.. highlightlang:: html+django 863 864The ``cms_toolbar`` template tag is included in the ``cms_tags`` library and will add the required 865CSS and javascript to the sekizai blocks in the base template. The template tag must be placed 866before any ``{% placeholder %}`` occurrences within your HTML. 867 868.. important:: 869 870 ``{% cms_toolbar %}`` will only work correctly inside the template's ``<body>``. 871 872 873Example:: 874 875 <body> 876 {% cms_toolbar %} 877 {% placeholder "home" %} 878 ... 879 880 881.. note:: 882 883 Be aware that you cannot surround the ``cms_toolbar`` tag with block tags. 884 The toolbar tag will render everything below it to collect all plugins and placeholders, before 885 it renders itself. Block tags interfere with this. 886