1 2Creating Templates for Using with Htpl Library 3================================================================ 4 5 6Macros 7============================ 8 9Macro starts and ends with '@' sign. When line's parsing is done the macro 10is substututed with its value. 11 12 Example: '@var1@' expands to the value of macro 'var1'. 13 14To place a '@' sign to template, escape it with a '\' sign. 15 16 Example: '\@var1\@' expands to string '@var1@'. 17 18If macro's name is not found in the list of local variables of template, then 19it is assumed that this macro is a system environment variable. 20 21 Example: '@sysvar@' expands to the value of environment variable 'sysvar'. 22 23 24Sections 25============================ 26 27Parser directives: 28#include <filename> 29#section <name> 30#endsection 31 32Template file consists of one or several sections. (It can contain no sections, 33but such file should not be called a template.) 34 35Section begins with "#section <name>" and ends with "#endsection" directives. 36Each directive should be located on a separate line. 37 38Each section should be located in one file: it cannot begin in one file and 39end in another included file. 40 41If line of template is out of any section, it is simply skipped when template 42parsing is performed. So, such lines can be used as comments. 43 44 Example: 45 46 #section header 47 ... 48 #endsection 49 50 #include template.tpl 51 52 #section footer 53 ... 54 #endsection 55 56 57Condition blocks 58================================ 59 60Parser directives: 61#if <expression> 62#ifdef <variable> 63#ifndef <variable> 64#elseif <expression> 65#else 66#endif 67 68Condition directives are used to parse lines of section by condition. 69 70The following expressions can be used with if or elseif commands: 71 @var@ == value 72 @var@ != value 73 @var@ =~ pattern 74 @var@ !~ pattern 75 76Part of line that contains an expression is expanded before expression is 77evaluated. 78 79If condition is true, then all the lines till #endif directive will be parsed, 80or they will be skipped if expression is false. 81 82"ifdef" block is true if <variable>'s value is defined. 83 84"ifndef" block is true if <variable>'s value is not defined. 85 86Condition block can be included in another condition block. 87 88 Example: 89 90 #if "@var@" == "value" <-- beginning of first condition block 91 ... 92 #ifdef @var1@ <-- beginning of second condition block 93 ... 94 #endif <-- end of second condition block 95 ... 96 #else <-- continue of first condition block 97 ... 98 #endif <-- end of first condition block 99 100 101Formatting 102================================ 103 104There are two methods of formatting: 1051) formatting macros 1062) formatting strings 107 108To format a macro you should write % sign after its name and write format 109pattern. Pattern can be written in 2 ways: 110 1111) <align sign><maximum length> 112 113 In this case macro's name will be drawn aligned to <align sign> 114 not more than <maximum length> characters. 115 1162) <align sign><align sign><align sign><align sign> (repeats several times) 117 118 The same, but maximum length is calculated by length of all macro 119 (including '@' signs). 120 121Align signs: 122 '<' - align to left (default) 123 '>' - align to right 124 '|' - align to center 125 126 Examples: 127 128 Macro: @time%40@ 129 Output: "Sat Jul 27 15:35:18 EEST 2002 " 130 131 Macro: @time%|40@ 132 Output: " Sat Jul 27 15:35:18 EEST 2002 " 133 134 Macro: @time%||||||||||||||||||||||||||||@ 135 Output: " Sat Jul 27 15:35:18 EEST 2002 " 136 137 Macro: @time%<<<<<<<<<<<<<<<<<<<<<<<<<<<<@ 138 Output: "Sat Jul 27 15:35:18 EEST 2002 " 139 140 Macro: @time%>>>>>>>>>>>>>>>>>>>>>>>>>>>>@ 141 Output: " Sat Jul 27 15:35:18 EEST 2002" 142 143To format a string you should write format pattern between '%' signs at the end 144of string to be formatted. Format pattern: 145 146 <maximum length>{<fill substring>} 147 148'{}' pattern indicates a place to be filled with <fill substring> untill 149the formatted line length is <maximum length>. 150 151 Example: 152 153 Template line... 154 155 @status%1@ @areaTag@ {} "@description@"%76{.}% 156 157 ..will be expanded to: 158 159 * 910.ANNOUNCE ........................................ "Fileecho announces" 160 161