Warning, /frameworks/ktexttemplate/docs/for_themers.dox is written in an unsupported language. File is not indexed.

 namespace KTextTemplate
 {
 
 /**
 
   @page for_themers KTextTemplate for theme artists
 
   The syntax of %KTextTemplate templates is the same as Django templates. This page is an introduction to the syntax, but any Django template introduction is also relevant. Here's some good ones:
 
   - https://djangobook.com/mdj2-django-templates/
   - https://djangobook.com/extending-template-system/
   - http://docs.djangoproject.com/en/dev/topics/templates/
 
 
   @section template_syntax Syntax of KTextTemplate templates
 
   The syntax of %KTextTemplate templates contains four types of tokens - plain text, comments, variables and control tags.
 
   A simple template might look like this:
   @verbatim
     {# My simple Template #}
 
     Hello {{ person.name }},
 
     {% if person.hasBirthday %}
     Happy Birthday!
     {% else %}
     Have a nice day!
     {% endif %}
 
     Bye,
 
     {{ myname }}
   @endverbatim
 
   - Content inside <tt>{# #}</tt> are comments and are not part of the output.
   - Content inside <tt>{{ }}</tt> are variables which are substitued when the template is rendered.
   - Content inside <tt>{% %}</tt> are control tags which can affect the rendering of the template. %KTextTemplate ships with commonly used tags such as @gr_tag{if}, @gr_tag{for}, @gr_tag{cycle} and a host of others (see&nbsp;http://docs.djangoproject.com/en/dev/ref/templates/builtins/). It is also possible for application developers and artists to define their own tags.
 
 
   @subsection loops Loops
   The type of a variable determines how it can be used in templates. For example, treatment of items in an iterable context works as follows.
 
   Lists work as expected:
   @verbatim
     <h2>A few of my favourite things</h2>
     <ul>
     {% for item in mylist %}
     <li>{{ item }}</li>
     {% endfor %}
     </ul>
   @endverbatim
 
   If an <tt>int</tt> or <tt>double</tt> is used in a loop, it is treated as a list containing one item. That is, this
 
   @verbatim
     {% for item in myint %}
     <li>{{ item }}</li>
     {% endfor %}
   @endverbatim
 
   would be rendered as
   @verbatim
     <li>6</li>
   @endverbatim
 
   if <tt>myint</tt> is <tt>6</tt> in the context.
 
   @subsection truthiness Truthiness
 
   Truthiness of a variable is evaulated in a similar way to python. That is,
 
   - The invalid QVariant is <tt>false</tt>
   - An empty QString is <tt>false</tt>
   - 0 is <tt>false</tt>
   - An empty container such as QVariantList or QVariantHash is <tt>false</tt>
   - Boolean <tt>false</tt> is <tt>false</tt>
   - QObjects that define their own truth behaviour and return <tt>false</tt> are <tt>false</tt>
 
   Everything else is <tt>true</tt>.
 
   @verbatim
     {% if mylist %}
     <ul>
     {% for item in mylist %}
     <li>{{ item }}</li>
     {% endfor %}
     </ul>
     {% endif %}
   @endverbatim
 
   @subsection lookups Variable lookups
 
   So far we've mostly used simple variable lookups in @gr_var{variable} tags, but the template system is capable of a lot more. Complex structures can be evaluated using the dot (<tt>'.'</tt>) character.
 
   The dot can be used for list index lookup (Note that list lookup is <tt>0</tt>-indexed):
   @verbatim
     The first item is {{ mylist.0 }}, and the fifth item is {{ mylist.4 }}.
   @endverbatim
 
   It can also be used for QVariantHash key lookup:
 
   @verbatim
     The hash value is {{ myhash.mykey }}.
   @endverbatim
 
   And it can retrieve properties from QObject instances:
 
   @verbatim
     The object property is {{ myobj.myprop }}.
   @endverbatim
 
   @subsection filters Filters
 
   Filters can further affect the result of including a variable in a template. Filters are separated by the pipe (<tt>'|'</tt>) character.
 
   @verbatim
     Name is {{ name }}, and name in uppercase is {{ name|upper }}.
 
     // rendered as
     // Name is Alice, and name in uppercase is ALICE.
   @endverbatim
 
   Note that filters may be combined with dot-lookup. For example, if <tt>people</tt> is a list of <tt>Person</tt> objects,
   and <tt>Person</tt> objects have <tt>name</tt> properties:
 
   @verbatim
     First persons name: {{ people.0.name|upper }}.
 
     // rendered as
     // First persons name: BOB.
   @endverbatim
 
   Filters may also be chained. Here, 'Claire' is first uppercased, then lowercased:
 
   @verbatim
     Name is {{ name|upper|lower }}
 
     // rendered as
     // First persons name: claire.
   @endverbatim
 
   Filters may take one string argument, which is delimited by a colon (<tt>':'</tt>).
 
   If <tt>peoplestring</tt> contains <tt>"Dave and Ellen and Frank"</tt>, we can cut the string <tt>'and '</tt>
 
   @verbatim
     The people are {{ peoplestring|cut:"and " }}
 
     // rendered as
     // The people are Dave Ellen Frank.
   @endverbatim
 
   %KTextTemplate ships with many useful filters including <tt>upper</tt>, <tt>lower</tt>, <tt>slice</tt>, <tt>truncate</tt>, <tt>join</tt>, <tt>split</tt> etc (see&nbsp;http://docs.djangoproject.com/en/dev/ref/templates/builtins/). Application developers and artists can also define their own filters.
 
   @subsection template_loading Template Inclusion and Inheritance
 
   It is possible for templates to include other templates in two ways, by directly including the content of another template, and by extending another template.
 
   @subsubsection template_including
 
   The @gr_tag{include} tag is used to include the content of another template.
 
   @verbatim
     <h1>My page</h1>
       {% include "breadcrumbs.html" %}
 
     <h2>My Data</h2>
       {% include "table.html" %}
   @endverbatim
 
   If <tt>"breadcrumbs.html"</tt> and <tt>"table.html"</tt> exist and contain appropriate content, they will be rendered and added to the output of the template.
 
   @subsubsection template_extending
 
   The @gr_tag{extends} tag is used to include and override the content of another template.
 
   The template being extended must define several blocks using the @gr_tag{block} tag. Typically, one or more base templates will be defined which define the structure and content of all templates, and some placeholders for other templates to fill in.
 
   For example, a <tt>base.html</tt> might look like this:
 
   @verbatim
     <html>
       <head>
         <title>{% block title %}My Stuff{% endblock %}</title>
       </head>
       <body>
         <div class="sidebar">
           {% block sidebar %}
           {% endblock sidebar %}
         </div>
         <div class="main_content">
           {% block content %}
           {% endblock content %}
         </div>
       </body>
     </html>
   @endverbatim
 
   Then other templates could be written which extend this template, reusing its content and replacing the content of the @gr_tag{block} tags.
 
   For example, a page about books:
 
   @verbatim
     {% extends "base.html" %}
     {% block title %}{{ block.super }} - My Books{% endblock %}
 
     {% block content %}
     <ul>
       {% for book in books %}
         <li>{{ book.name }}, {{ book.author }}
       {% endfor %}
     </ul>
     {% endblock %}
   @endverbatim
 
   Or a page about DVDs:
 
   @verbatim
     {% extends "base.html" %}
     {% block title %}{{ block.super }} - My DVDs{% endblock %}
 
     {% block content %}
     <ul>
       {% for dvd in dvds %}
         <li>{{ dvd.title }}, {{ dvd.director }}
       {% endfor %}
     </ul>
     {% endblock content %}
   @endverbatim
 
   Note that it is optional to override a @gr_tag{block} in a extended template. It is also optional to repeat the name of the block in its corresponding @gr_tag{endblock} tag.
 
   The content of an overriden tag is available in the @gr_var{block.super} variable, and can be reused where appropriate. In the above examples, the use of @gr_var{block.super} results in the titles of the rendered pages being <tt>"My Stuff - My Books"</tt>, and <tt>"My Stuff - My DVDs"</tt> respectively.
 
   @section templates_safestring Autoescaping in templates.
 
   When creating HTML string output it is necessary to consider escaping data inserted into the template. HTML escaping involves replacing <tt>'&lt;'</tt> with <tt>'&amp;lt;'</tt> and <tt>'&amp;'</tt> with <tt>'&amp;amp;'</tt> etc. %KTextTemplate automatically escapes string input before adding it to the output.
 
   This is relevant when writing a variable from the context into the Template.
 
   If the context object <tt>companies</tt> is a list containing (<tt>'Burger King'</tt>, <tt>'Ben &amp; Jerries'</tt>, <tt>'Ford'</tt>), and it is used in a template such as:
 
   @verbatim
     <ul>
     {% for company in companies %}
       <li>{{ company }}</li>
     {% endfor %}
     </ul>
   @endverbatim
 
   The output would be
 
   @verbatim
     <ul>
       <li>Burger King</li>
       <li>Ben &amp; Jerries</li>
       <li>Ford</li>
     </ul>
   @endverbatim
 
   Notice that the <tt>'&amp;'</tt> has been replaced with <tt>'&amp;amp;'</tt>, as is appropriate for html output.
 
   Sometimes however, a variable will contain text which has already been escaped and does not need to be escaped again. For example,
   if we already created a <tt>table</tt> in the context containing the content:
 
   @verbatim
     <table class="myclass">
       <tr><th> Company </th><th> Product </th></tr>
       <tr><td> Burger King </td><td> Fast Food </td></tr>
       <tr><td> Ben &amp; Jerries </td><td> Icecream </td></tr>
       <tr><td> Ford </td><td> Cars </td></tr>
     </table>
   @endverbatim
 
   and a template with the content:
 
   @verbatim
     <h2> Table of companies </h2>
 
     {{ table }}
 
     As you can see in the table...
   @endverbatim
 
   the content would not be rendered properly because it would be escaped.
 
   @verbatim
     <h2> Table of companies </h2>
 
     &lt;table class=&quot;myclass&quot;&gt;
       &lt;tr&gt;&lt;th&gt; Company &lt;/th&gt;&lt;th&gt; Product &lt;/th&gt;&lt;/tr&gt;
       &lt;tr&gt;&lt;td&gt; Burger King &lt;/td&gt;&lt;td&gt; Fast Food &lt;/td&gt;&lt;/tr&gt;
       &lt;tr&gt;&lt;td&gt; Ben &amp;amp; Jerries &lt;/td&gt;&lt;td&gt; Icecream &lt;/td&gt;&lt;/tr&gt;
       &lt;tr&gt;&lt;td&gt; Ford &lt;/td&gt;&lt;td&gt; Cars &lt;/td&gt;&lt;/tr&gt;
     &lt;/table&gt;
 
     As you can see in the table...
   @endverbatim
 
   Note that the content of <tt>table</tt> has already been escaped. That is <tt>'Ben &amp;amp; Jerries'</tt> is already used instead of <tt>'Ben &amp; Jerries'</tt>. If a variable has already been escaped and should not be escaped again, it can be marked as safe from further escaping using the <tt>safe</tt> filter.
 
   @verbatim
     <h2> Table of companies </h2>
 
     {{ table|safe }}
 
     As you can see in the table...
   @endverbatim
 
   Resulting in:
 
   @verbatim
     <h2> Table of companies </h2>
 
     <table class="myclass">
       <tr><th> Company </th><th> Product </th></tr>
       <tr><td> Burger King </td><td> Fast Food </td></tr>
       <tr><td> Ben &amp; Jerries </td><td> Icecream </td></tr>
       <tr><td> Ford </td><td> Cars </td></tr>
     </table>
 
     As you can see in the table...
   @endverbatim
 
   It is also possible to turn this autoescaping feature off for a block in a template.
 
   For example:
 
   @verbatim
     <h2> Some pre-prepared safe data </h2>
 
     {% autoescape off %}
       {{ table }}
       As you can see in the table...
 
       {% for list in lists %}
         {{ list }}
       {% endfor %}
 
       {{ paragraph_data }}
     {% endautoescape %}
   @endverbatim
 
   would not escape the content between the <tt>autoescape</tt> and <tt>endautoescape</tt> tags. This should only be used for content which is actually already safe.
 
   @see https://docs.djangoproject.com/en/1.9/ref/templates/language/#for-individual-variables
 
   @subsection extending_syntax Extending the syntax
 
   It is also possible to extend the syntax of %KTextTemplate as you need it using Javascript if the application developer chooses. See @ref javascript_libraries for more. This is considered an advanced topic.
 
 */
 
 }