nxweb Templates
22.09.2014Hierarchy
nxweb templates are organized in hierarchies. One template can inherit structure from another and provide new values for previously defined blocks.
parent.thtml
<html>
<head><title>{% block page-title %}Initial Title{% endblock %}</title></head>
<body>
<h1>{% block page-title %}{% endblock %}</h1>
{% block page-content %}
<p>Initial content.</p>
{% endblock %}
</body>
</html>child.thtml
{% extends parent.thtml %}
{% block page-title %}Child Page{% endblock %}
{% block page-content %}
<p>Child page content.</p>
{% endblock %}Requesting child.thtml results in the following code:
<html>
<head><title>Child Page</title></head>
<body>
<h1>Child Page</h1>
<p>Child page content.</p>
</body>
</html>Supported directives
{% block block-name %}... block content ...{% endblock %}
This directive is dual-purpose.
When used inside other block it marks place where block named block-name should be inserted.
When directive is not empty, i.e. has block content it also defines new content for block block-name. Content defined by child templates overrides content defined by parent(s).
{% extends uri1 ... %}
{% use uri1 ... %}
These two are actually synonyms. The difference is in semantics only. Your page ususally extends one base template providing structure and can also use blocks from several secondary templates.
You can list multiple URIs separated by a space. URIs can be surrounded by single or double quotes.
Extending or using an URI makes subrequest to it. URIs can only contain a path (i.e. cannot change domain), absolute or relative to current template's URI.
{% include uri %}
By including an URI you make subrequest to it and paste result in specified location. In case included URI contains template it is processed separately from current one, only result is pasted.
{% parent %}
By using this directive you insert content defined for current block in parent template into newly defined content therefore merging child with parent. For example:
{% block page-content %} {% parent %} <p>Child page content.</p> {% endblock %}results in:
<html> <head><title>Child Page</title></head> <body> <h1>Child Page</h1> <p>Initial content.</p> <p>Child page content.</p> </body> </html>
{% raw %}... unparsed content ...{% endraw %}
This way you can protect some content containing templates markup characters from being parsed as template. Make sure unparsed content does not include {% endraw %} directive cause it terminates escaped block.
nxweb Configuration
In order to use nxweb templates engine you have to add templates filter to your routing records. Let's take our Python Flask configuration and add templates filter to it.
nxweb_config.json
{
"prefix":null, // "vhost":".mydomain.com",
"handler":"python", // "uri":"/my/path/info",
"dir":"cache/upload_temp", "size":50000000 /* 50Mb max upload */,
"filters":[
{"type":"file_cache", "cache_dir":"cache/python"},
{"type":"templates"}
]
}Mark content as templates
Adding templates filter does not mean that every server response will be processed as templates. In order to activate templates for particular response it should be marked as templates content. This can be done in one of three ways:
- for static files served by
sendfilehandler use file extension.thtml - alternatively for static files served by
sendfilehandler use sticky bit:chmod +t myfile.htm - for dynamic content (from Python or HTTP-proxy) add special header to your response:
X-NXWEB-Templates: ON
You don't have to mark as templates content fetched through {% extends %} or {% use %} directives – it is processed as template automatically.
Why templates at web server level?
As you can see nxweb templates are not as functional as application level templates like Django, Jinja2, or Twig. They do not support variables, loops, etc. But they are still quite useful:
- nxweb templates provide flexible means of page assembly (much more flexible than Server Side Includes)
- nxweb templates are fast
- most importantly nxweb templates enable efficient block level caching strategy (different parts of a web page can have different expiration times so these better cached separately, then assembled by web server)
Comments