Table of Contents
A "afd:extension" tag declares the relationship of inheritance between child template and parent template.
Attributes:
Identifies the parent template file of the current template.
A "afd:block" tag declares a referenceable block in the template file. Child template file can reference the blocks in parent template by the same tag "afd:block" with extra action declaration: append, insert, override.
Example 10.2. parent.html
<html> <head> <afd:block id="block1"> <link href="parent1.css" rel="stylesheet" type="text/css" /> </afd:block> <afd:block id="block2"> <link href="parent2.css" rel="stylesheet" type="text/css" /> </afd:block> <title>extension sample</title> </head> <body> <afd:block id="content">content</afd:block> </body> </html>
Example 10.3. child.html
<afd:extension parent="parent.html"> <afd:block append="block1"> <link href="child1.css" rel="stylesheet" type="text/css" /> </afd:block> <afd:block insert="block2"> <link href="child2.css" rel="stylesheet" type="text/css" /> </afd:block> <afd:block override="content"> <div>hello</div> </afd:block> </afd:extension>
Attributes:
The referenceable id of a block.
Append all the children of current tag to the tail of the parent's block which id equals the declared value of the append attribute.
Insert all the children of current tag to the head of the parent's block which id equals the declared value of the insert attribute.
Override the parent's block which id equals the declared value of the override attribute by all the children of current tag.
The result of merging the above two files by Asta4D's template engine can be found at Chapter 2, Flexible template.
A "afd:embed" tag declares an action of extracting and inserting an external file's content to the site where the "afd:embed" tag is declared.
Example 10.4. child.html
<afd:extension parent="parent.html"> <afd:block override="content "> <div>hello</div> <afd:embed target="/templates/embed.html" ></afd:embed> </afd:block> </afd:extension>
Attributes:
The path of which file should be included at the declaration site.
In the embed target file, afd:block can also be used to append/insert/override the blocks in source template. Samples and the merging result can be found at Chapter 2, Flexible template.
A "afd:snippet" tag declares an Java class which assumes the duty of rendering data to the html snippet contained by the declaring tag.
Example 10.5.
<afd:snippet render="SimpleSnippet:setProfile"> <p id="name">name:<span>dummy name</span></p> <p id="age">age:<span>0</span></p> </afd:snippet>
Attributes:
The snippet class name and render method name by format:<class name>:<method name>, the class name and the method name are split by colon. If the method name is omitted, the default method name "render" will be used.
A snippet tag with "parallel" attribute will be executed in a separated thread from the main thread of current http request. It is not necessary to assign a value to this attribute.
A snippet tag with "clear" attribute will not be executed and will be removed from the final output page. This is useful for disabling certain contents temporarily in certain situations such as debug. It is not necessary to assign a value to this attribute.
There is an alternative way to declare a snippet by "afd:render" attribute.
Example 10.6.
<div afd:render="SimpleSnippet:setProfile"> <p id="name">name:<span>dummy name</span></p> <p id="age">age:<span>0</span></p> </div>
By the same way, "afd:paralell" and "afd:clear" can be used on arbitrary html tags which will be treated as the same as a "afd:snippet" tag. Note that "afd:paralell" will not be available except the "afd:render" is declared too, but the "afd:clear" will be always available even there is no declaration of "afd:render" on the html tag.
A "afd:group" tag declares a referenceable DOM element for back-end Java snippet class. It is useful to reference certain text without wrapping html tag or combine a group of coordinate html tags as a single node.
Example 10.7.
<p>We found <afd:group id="item-count">3</afd:group> matched items in our database.</p> <afd:group id="list-item"> <div id="title">the title</div> <div id="content">the content</div> </afd:group>
Attributes:
None.A "afd:comment" tag declares a comment block in the template files and it will be removed after rendering.
Example 10.8.
<afd:comment>This is comment</afd:comment> <afd:comment> <div>This is comment too.</div> </afd:comment>
Attributes:
None.A "afd:msg" tag declares a message managed in external files. This tag is mainly designed for i18n support, but it also can be used as a simple string replacer. Please see Chapter 15, i18n for more details.
Attributes:
The message key which should can be found in the configured message file.
HTML5 convention
Asta4D's template engine does only support html5, which relies on the underline library jsoup(verion 1.6.3). jsoup implements the WHATWG HTML5 specification and requires compliance from the target file. jsoup can fix some cases of breaking specification but you would still get unexpected result for certain cases. Basically, you should take care of the following things:
All tags and attributes are converted to lower case.
Self closed tags such as <div /> or <afd:embed target="embed.html" /> is not legal.
There are some tags that the parser "ensures".For example a <tbody> tag must be the first tag inside <table>, which breas the following example:
Example 10.10.
<table> <afd:snippet render="ListSnippet"> <tr><td></td></tr> </afd:snippet> </table>
But it can be replaced by the following:
body convention
When a child template file uses "afd:extension" to declare its parent template, only the body part(all the children of the body except the body tag itself) of the child template will be processed by the template engine and the parts out of body will be ignored simply. The same convention is applied to the embed target file. The following two sample will not cause different results by Asta4D.
Example 10.12. child.html without body tag:
<afd:extension parent="parent.html"> <afd:block override="content "> <div>hello</div> <afd:embed target="/templates/embed.html" ></afd:embed> </afd:block> </afd:extension>
Example 10.13. child.html with body tag:
<html> <head> <meta charset="UTF-8"> </head> <body> <afd:extension parent="parent.html"> <afd:block override="content "> <div>hello</div> <afd:embed target="/templates/embed.html" ></afd:embed> </afd:block> </afd:extension> </body> </html>
This convention can be used for editor compatibility in case of your prefer html editor requires correct meta information (We add charset="UTF-8" to all of our template files for this reason). Note that this convention is only available on extended child template file or embedded target file, the parts out of body tag will be processed normally in the parent template file which is as a root template without further parent.
Further, explicit parameter information can be commented at body tag in parameterizable embed target file for better source readability.
Example 10.14. embed.html
<html> <head><meta charset="UTF-8"></head> <body itemsize="{Integer}" itemlist="{List}"> <afd:block append="block1"> <link href="embed.css" rel="stylesheet" type="text/css" /> </afd:block> <div>good embed</div> </body> </html>
In Example 10.14, “embed.html”, we put some "strange" information in the body tag, which suggests that when this file is embedded, it requires an Integer parameter named "itemsize" and a List parameter named "itemlist". Note that such declaration can only be regarded as a hint for source reader and there is no warranty about any parameter check. You should consider it as a sample of how you can make interesting use of the body convention.
"afd" name space
The "afd" name space is configured as the default name space of Asta4D's special tags. This name space can be changed by Configuration#setTagNameSpace.
TemplateResolver
Asta4D searches certain template file by configured TemplateResolver. There are three pre-implemented TemplateResolver: FileTemplateResolver, ClasspathTemplateResolver and WebApplicationTemplateResolver. The default configured WebApplicationTemplateResolver will search template files with awareness of servlet container. The FileTemplateResolver and ClasspathTemplateResolver can be used for test purpose, you can also provide your own TemplateResolver for special search mechanism.