Template Locations

If your going to use the run_templater method in your app (and this is recommended) then your templates will need to be in the templates subdirectory of the Bricklayer root directory or a diectory under this one. Using the run_templater method gives you one useful benefit. Automatic handling of subdirectories in the template directory location. Believe me if you have a lot of templates this can be a lifesaver. It does this by the simple expedient of seperating out directories with the : character. For instance a page request formatted like this: gallery:thumbnails will look for the template in the gallery subdirectory of the templates directory. Usually a Bricklayer template has an extension of .txml. This is not a hard and fast rule though so feel free to break it if you really want to. Of course if you do then the provided execute and execute_web Bricklayer methods won't work since they expect the extension to be .txml You can nest template tags as deep as the tag handler will allow. Just remember that if you use a template tag as a container tag the handler has to parse the contents. So pay attention to what your tags will be expected to do. Template tags can occur anywhere in the template. Even though they look like XML elements they don't have to obey the rules of an xml element. They can occur inside xml or html elements. Here is an example template.

<html>
<head> 
	<meta content="" />
	<title>Default Index - testing</title>	
</head>
<body>

<div id="menu_main">
	<ul>
	<BKmenu>
		<li><BKmenu_item /></li>
	</BKmenu>
	</ul>
</div>

<div style="<BKstyle />" id="bklog">
	<BKbk_log />
</div>
</body>
</html>

Note the BK identifiers on the elements. This is the default indentifier for Bricklayer templates but it is cusomizable. Also the template tags can appear inside attributes and nest inside each other. Each tag will be replaced in the document with whatever it's handler returns. Tag's can appear literally anywhere in the document. There some rules to keep in mind though. Container tags can't cross each other's boundaries or there will be an error in the sequencer. This will cause the sequencer to error for example:

<BKtag1>
<BKtag2>
</BKtag1> These two tags cross each others boundaries.
</BKtag2>

Container tags must also close themselves or the results will be unpredictable.

As you can see we leave you a lot of room to maneuver in the tag handlers. Container tags will probably be used for looping and conditional processing. You can literally create your own Coldfusion like language with this engine. Feel free to use them however you feel like. They do one thing and one thing well. The rest is up to you.

Jeremy Wall 2006-08-21