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.

*/

}
