doc: migrated docs for a few tags.

doc/ref/.gitignore

@@ -1,4 +1,6 @@
 *.rst
 !doc-*.rst
 !index.rst
+!tag_*
+*~
 meta-*

doc/ref/tags/index.rst

@@ -1,7 +1,12 @@
 .. _tags:
 
-Tags
-====
+:index:`Tags`
+=============
 
 When you are trying to find a tag used in a template, and it is not listed here, then check the list of all :ref:`scomps` as the :ref:`manual-scomps` syntax is identical to the :ref:`manual-tags` syntax.
 
+.. toctree::
+   :glob:
+
+   tag_*
+

doc/ref/tags/tag_all-catinclude.rst

@@ -0,0 +1,28 @@
+.. index:: tag; all catinclude
+.. _tag-all-catinclude:
+
+all catinclude
+==============
+
+Include a template for all a resource's categories from all modules.
+
+This is an extension on the :ref:`tag-catinclude` tag.  It will include all templates with the given name, instead of the first one found.  Templates are defined in modules, because of that multiple modules can define a template with the same name.
+
+This catinclude extension will include all available templates in the same order as defined in :ref:`tag-catinclude`.  Where the templates per category will be rendered in the order of their module's defined priority. This is the order in which they are listed in the module admin page.
+
+Examples of this mechanism can be found in :ref:`mod_admin`, for example the main menu and the category specific editing fields on the edit page.
+
+An example usage::
+
+   {% all catinclude "hello.tpl" id arg="val" %} 
+
+Includes all templates with the base name `hello.tpl` for the id's category hierarchy.  
+
+For example, in the case of a *news* article:
+
+* all templates with the name .hello.news.tpl.
+* all templates with the name .hello.article.tpl.
+* all templates with the name .hello.text.tpl.
+* all templates with the name .hello.tpl.
+
+.. seealso:: tags :ref:`tag-catinclude` and :ref:`tag-all-include`.

doc/ref/tags/tag_all-include.rst

@@ -0,0 +1,34 @@
+.. index:: tag; all include
+.. _tag-all-include:
+
+all include
+===========
+
+Call all modules to include a certain template.
+
+This is an extension on the :ref:`tag-include` tag. It will include all templates with the given name, instead of the first one found.  Templates are defined in modules, because of that multiple modules can define a template with the same name.
+
+For example when you have two modules (`mod_a` and `mod_b`), both with the template `_name.tpl`.  When the template in `mod_a` is defined as::
+
+   this is mod_a's {{ hello }}
+
+and in mod_b as::
+
+   this is mod_b's {{ hello }}
+
+then the tag::
+
+   {% all include "_name.tpl" hello="world" %}
+
+Will output::
+
+   this is mod_a's world
+   this is mod_b's world
+
+The modules will be called in the order of their defined priority. This is the order in which they are listed in the module admin page.
+
+Examples of this mechanism can be found in :ref:`mod_admin`, for example the main menu and the category specific editing fields on the edit page.
+
+Another example is the `_html_head.tpl` template which is included from the :ref:`template-base` template and allows all modules to add HTML to the head of a generated HTML page.
+
+.. seealso:: tag :ref:`tag-include`.

doc/ref/tags/tag_autoescape.rst

@@ -0,0 +1,23 @@
+.. index:: tag; autoescape
+.. _tag-autoescape:
+
+autoescape
+==========
+
+Automatically apply HTML escaping to values.
+
+The `autoescape` tag controls the current auto-escaping behavior. This tag takes either `on` or `off` as an argument and that determines whether auto-escaping is in effect inside the block.
+
+When auto-escaping is in effect, all variable content has HTML escaping applied to it before placing the result into the output (but after any filters have been applied). This is equivalent to manually applying the escape filter to each variable.
+
+Example::
+
+   {{ value }}
+   {% autoescape on %}
+     {{ value }}
+   {% endautoescape %}
+
+When the variable value contains `<b>Hello</b>` then this will output::
+
+   <b>Hello</b>
+   &lt;b%gt;Hello&lt;/b&gt;

doc/ref/tags/tag_block.rst

@@ -0,0 +1,34 @@
+.. index:: tag; block
+.. _tag-block:
+
+block
+=====
+
+Overrule a block from an inherited template.
+
+The `block` tag is used for replacing blocks in inherited templates.
+
+For example, when we have a template `base.tpl`::
+
+   Hello {% block name %}my{% endblock %} world.
+
+And we render the template::
+
+   {% extends "base.tpl" %}
+   {% block name %}Peter's{% endblock %}
+
+Then the output will be::
+
+   Hello Peter's world.
+
+Though when we render the template::
+
+   {% extends "base.tpl" %}
+
+then the output will be::
+
+   Hello my world.
+
+The name of a block must be a valid identifier.
+
+.. seealso:: :ref:`tag-extends` and :ref:`tag-overrules`.

doc/ref/tags/tag_catinclude.rst

@@ -0,0 +1,30 @@
+.. index:: tag; catinclude
+.. _tag-catinclude:
+
+catinclude
+==========
+
+Include another template based on the category of a resource. The include tag is replaced with the contents of the included template file. You can give arguments to the included template, they will be assigned as variables in the context of the included template.
+
+Example::
+
+   {% catinclude "hello.tpl" id %}
+
+Assuming that the resource whose id is the value of the template variable `id` is a news article then catinclude will consider the following templates::
+
+   hello.news.tpl
+   hello.article.tpl
+   hello.text.tpl
+   hello.tpl
+
+This because `news` is a subcategory of `article`, which is a subcategory of `text`. When one of the previous templates is not found then the base template `hello.tpl` is tried. The catinclude tag will only include the first file it finds, and stops after having found a file to include.
+
+Unlike Django the template name must be a string literal, variables are not allowed.
+
+The tag accepts extra arguments, which will be passed as template variables to the included template. The inclusion is always done at runtime, because the selected template depends on the category of the referenced resource.
+
+The resource id will be available in the included template as the variable `id`.
+
+See the :ref:`tag-include` for caching options and argument handling.
+
+.. seealso:: :ref:`tag-all-catinclude`, which is useful to include multiple templates.

doc/ref/tags/tag_extends.rst

@@ -0,0 +1,21 @@
+.. index:: tag;  extends
+.. _tag-extends:
+
+extends
+=======
+
+Inherit markup from another template.
+
+Signal that this template extends another template. The extends tag must be the first tag in a template that inherits from another template.
+
+.. note:: A template that extends another template contains only the extends tag and block tags.
+
+Example::
+
+   {% extends "base.tpl" %}
+
+All named blocks in this template will replace the similar named blocks in the template `base.tpl`.
+
+Unlike Django the template name must be a string literal, variables are not allowed.
+
+.. seealso:: :ref:`tag-block`, :ref:`tag-inherit` and :ref:`tag-overrules`.

doc/ref/tags/tag_include.rst

@@ -0,0 +1,66 @@
+.. index:: tag; include
+.. _tag-include:
+
+include
+=======
+
+Include another template. The include tag is replaced with the contents of the included template file. You can give arguments to the included template, they will be assigned as variables in the context of the included template.
+
+Example::
+
+   {% include "_hello.tpl" name="Peter" %} world.
+
+When `_hello.tpl` contains the text::
+
+   Hello {{ name }}'s
+
+Then this will output the text ``Hello Peter's world.``.
+
+Unlike Django the template name must be a string literal, variables are not allowed.
+
+.. note::
+   About unique ids
+      :index:`Automatically generated ids` (#name) are :index:`unique <pair: unique; id>` within an included template and do not clash with similarly named ids in the including template.
+
+.. seealso:: :ref:`tag-all-include` and :ref:`tag-catinclude`.
+
+
+Caching of the included template
+--------------------------------
+
+The output of the included template can be cached. This is useful when rendering the template takes considerable time. For example when the template shows a list of recent news items, which comprises a query, fetching and rendering a list of news items.
+
+Caching is enabled by defining one of the caching arguments:
+
++------------+--------------------------------------------------------+--------------------+
+|Argument    |Description                                             |Example             |
++============+========================================================+====================+
+|maxage      |The maximum time the output can be cached, in seconds.  |maxage=3600         |
+|            |Specifying 0 for the maximum age does not cache the     |                    |
+|            |output but does protect agains slam dunks, multiple     |                    |
+|            |requests rendering the same template at the same time   |                    |
+|            |will share the output of the rendering.                 |                    |
+|            |                                                        |                    |
++------------+--------------------------------------------------------+--------------------+
+|vary        |Dependency keys for the cached output. When a cache key |vary="news"         |
+|            |with the same name is flushed or invalidated then the   |                    |
+|            |cached output of this template is also invalidated. You |                    |
+|            |can use category names here.                            |                    |
+|            |                                                        |                    |
++------------+--------------------------------------------------------+--------------------+
+|visible_for |Sets the access control user for rendering the included |visible_for="world" |
+|            |template.  With this you can for example force to only  |                    |
+|            |show public news for logged on users.  Valid values are |                    |
+|            |"user", 3, "group", 2, "community", 1, "world",         |                    |
+|            |"public", 0                                             |                    |
+|            |                                                        |                    |
++------------+--------------------------------------------------------+--------------------+
+|sudo        |When supplied then access control is disabled whilst    |sudo                |
+|            |rendering the included template. This will show any     |                    |
+|            |content not visible for the current user.  Use with     |                    |
+|            |care.                                                   |                    |
+|            |                                                        |                    |
++------------+--------------------------------------------------------+--------------------+
+
+.. versionadded:: 0.6
+   Added the `sudo` option.

doc/ref/tags/tag_overrules.rst

@@ -0,0 +1,26 @@
+.. index:: tag; overrules
+.. _tag-overrules:
+
+overrules
+=========
+
+Inherit markup from like named template in another module.
+
+Signal that this template extends a template with the same name in a module with lower priority.
+
+The `overrules` tag must be the first tag in the template.
+
+.. note:: A template that overrules another template contains only the :ref:`tag-extends` tag and :ref:`tag-block` tags.
+
+Example, say a template "page.tpl" contains the following::
+
+   {% overrules %}
+   {% block title %} My new title {% endblock %}
+
+All named blocks in this template will replace the similar named blocks in the template `page.tpl` that is "next in line" to be used.
+
+This is useful if you want to use a template from a module, and the template is mentioned in (for example) a dispatch rule. Now you can overrule and extend that template in your own modules without changing the dispatch rules or the original module.
+
+Make sure your module has a higher priority (lower number) than the module containing the overruled template.
+
+.. seealso:: :ref:`tag-block`, :ref:`tag-inherit` and :ref:`tag-extends`.