ZZEE   AHT   Advanced HTML TOC 2.0
www.zzee.com | Index | You are here: Contents > 6. TOC templates

6. TOC templates


6.1. Predefined templates

www.zzee.com | Index | You are here: Contents > 6. TOC templates > 6.1. Predefined templates

The following templates are shipped. You can use them directly, adjust them or create new ones based on them. You also can combine features of several templates into one template.

  1. Tree.
  2. Tree with bullets.
  3. Expandable / collapsible tree. Fully supported by IE 5+ and Netscape 6+.
  4. Bulleted tree with "differentiated" headers.
  5. Indent based tree.
  6. Pure text. It is indent based too.

See description of each template by clicking Template description link.

The main point of providing predefined templates is to give you an idea how you can use ZZI to build your own templates.

See also: Format options.


6.2. Creating and modifying templates

www.zzee.com | Index | You are here: Contents > 6. TOC templates > 6.2. Creating and modifying templates

Template consists of a template file and a description in "zzdata/templates.txt" file.


6.2.1. How to add template to a drop-down select box

www.zzee.com | Index | You are here: Contents > 6. TOC templates > 6.2. Creating and modifying templates > 6.2.1. How to add template to a drop-down select box

File "templates.txt", located in "zzdata" folder, is needed to describe all templates that are available to the program. It is an XML file and it has the following syntax:

<templates>
	<template>
		<name>Name of a template</name>
		<file>Template file</file>
		<description>Description of a template</description>
	</template>
	...
</templates>

After adding template description to templates.txt, either select Options > Re-init Template Data from menu or restart the Software. It automatically adds the new template to the drop-down selection box.

See also: How to write own template file.


6.2.2. How to write own template file

www.zzee.com | Index | You are here: Contents > 6. TOC templates > 6.2. Creating and modifying templates > 6.2.2. How to write own template file

Templates use ZZI for text preprocessing, which is very basic text preprocessor.

See also: How to add template to a drop-down select box.


6.2.2.1. ZZI preprocessor

www.zzee.com | Index | You are here: Contents > 6. TOC templates > 6.2. Creating and modifying templates > 6.2.2. How to write own template file > 6.2.2.1. ZZI preprocessor

ZZI supports only 3 constructs:

  1. <!--#echo var="var_name"-->
    Outputs a value of a variable which name is var_name. No close tag is required.
     
  2. <!--#if var="var_name"-->
     Something if variable var_name is not zero
    <!--#else-->
     Something otherwise
    <!--#endif-->
    Does conditional output. Requires close tag <!--#endif-->. <!--#else--> is optional.
     
  3. <!--#for var="var_name"-->
     Something to repeat
    <!--#endfor-->
    Does loop so many times as there are variables with name var_name. Requires close tag <!--#endfor-->.

These constructs resemble SSI ones and are wrapped in HTML comments. All other attributes in them, except var, are ignored and can be used as comments.

All variables which can be used in the above constructs are predefined by the program, and user can not add or modify these variables.

Though TOC is a forest-like structure, ZZI doesn't support pointers, and it is linear processor. Therefore the software uses an intermediary TOC representation as a linear structure. To do this, the program has some service variables, such as item, open, children and level.

See also: Available variables, Sample template.


6.2.2.2. Available variables

www.zzee.com | Index | You are here: Contents > 6. TOC templates > 6.2. Creating and modifying templates > 6.2.2. How to write own template file > 6.2.2.2. Available variables

Templates can use the following predefined variables. You can not add, remove or modify variables.

Variable Meaning
text Text extracted from according header tag.
link Where TOC item should link to (matches named anchor within <h> tag).
numbering Numbering in decimal notation. If "Process numbering in decimal notation" checkbox is unchecked then numbering is empty.
item Service value, needed to do the main loop for the template. It also can be used as unique ID for TOC items, which may be needed in JavaScript, DOM, etc.
open Service value, needed just to distinguish node opening from its closing. It takes "1" or "0" values. Many block HTML tags require close tag. This variable helps building properly nested block tags. If open = 1, put start tag of a pair (e.g. <ul>), if open = 0, put close tag (e.g. </ul>) .
children Service value, needed to to guess if current item has any child items. It takes "1" or "0" values. For items which have open = 0, children means if there is any child item of according open item.
level Numeric value, the level of the node in TOC forest, where root level items (without parents) have level equal to zero, their children have level equal to one, etc. This is not the same thing as header tag numeric value (such as 2 for <h2>), because header tags may go outside of logical order, etc. But if you lay header tags out correctly and process file titles, then level should coincide with header tag numeric value.
indentation Text string. Composed from repeated level times indent string value, which is set on Format Options page. This is useful for custom formatting of the TOC.

See also: ZZI preprocessor, Sample template, Format options.


6.2.2.3. Generic template

www.zzee.com | Index | You are here: Contents > 6. TOC templates > 6.2. Creating and modifying templates > 6.2.2. How to write own template file > 6.2.2.3. Generic template

Below is the code of a sample template, it is to show the usage of service variables (item, open, children). If you create your own template, use this generic template or any of predefined templates as a base for your development.

<!--#for var="item"-->
	<!-- this is a main loop, variable "item" is used here only,
	though it can serve as a counter or ID as well -->


	<!--#if var="open"-->
		
		<!-- Put here code for any TOC item -->

		<!-- let's see if the item has any children, if it does,
		then we may need to lay it some other way than
		items that don't -->

		<!--#if var="children"-->
			<!-- put here code specific for the items
			that have child nodes -->
			
		<!--#else -->
			<!-- you may put here code for the items 
			that don't have child nodes -->
		
		<!--#endif -->


	<!--#else-->
		<!-- put here code that is needed for 
		correct finishing of any HTML block tag -->


	<!--#endif-->

<!--#endfor -->

See also: ZZI preprocessor, Available variables, Predefined templates.