NAME
VERSION
Version 2.21
DESCRIPTION
Standard tags and functions are the most used uHTML tags and functions - think std.h in C. They are used in nearly every uHTML project. It brings programming capabilities directly into the uHTML-files and addresses rather the programmer than the designer, although most designers value especially the tags include and define which use is quite obvious for them. The tags if/else, choice, repeat and macro are usually utilized with support of the programmer. Due their compliance with the standard HTML-syntax designers do not hesitate to alter them without help of the programmer. While doing that the designer seldom incorporate errors into the uHTML file as the tags program code is not affected and a faulty result can be noticed by the designer immediately.
REQUIREMENTS
This std library do not require any other libraries but the main uHTML library.
uHTML tags provided by the std library
include
Overview
The include tag includes the content of a uHTML file into another uHTML-file. It is intended to move constant parts of the website files like header lines, menus, footers, etc. into one file and save thereby development and maintenance time ans as well reduce probability of random mistakes.
Conventions
Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.
Attributes
file="FILEPATH"
The attribute file defines the path and name of the included file.
files="FILEPATH"
The attribute files defines the path and name of the included file whereby wildcards * and ? are expanded according to glob rules and the included files get concatenated.
alt="FILEPATH"
In case no file defined by the file or files attributes is found, the file defined by the alt attribute get included whereby wildcards * and ? are expanded according to glob rules and the included files get concatenated.
raw
The attribute raw without value prevents the interpretation of uHTML-elements in the included file. It should be used if files without uHTML-elements get included.
warn
The attribute warn without value allows error messages in case the included file isn't found or is not readable.
cond="clause"
The cond attribute is optional. If present, then the include tag is executed only if the clause in the attribute cond evaluates 'true'.
Example
<include file="/include/navigation" >define
Overview
The define tag defines new uHTML tags and variables assigning to each constant content which isn't interpreted as uHTML. It helps to shorten source files abbreviating frequently used code sequences. At the same time it reduces the risk of random errors while copying of the same content across the site's source files. It is possible to define several tags and variables within one define tag. It is advisable to use the include-tag to collect definitions used in the whole site in one file.
Conventions
Previous definitions with the same name are saved and get recovered when a definition done with define get revoked with undef unless the definition is done with the attribute replace.
Attributes
createonly
If a attribute createonly without any value is supplied, only new definitions will be regarded. Existing definitions will be skipped.
replace
If a attribute replace without any value is supplied, the last definition of a tag and variable will be replaced not recoverable by undef.
Example
Definition:
E<lt>define uHTML='E<lt>span style="font-family:serif;color:#34a;"E<gt>
E<lt>span style="font-weight:bold;color:#fe6f02; font-size:0.8em"E<gt>UE<lt>/span>HTMLE<lt>/spanE<gt>'
bluestyle="color:blue;font-weight:bold;"E<gt>Use:
<uHTML> <span style="$bluestyle"> is exciting </span>undef
Overview
The undef tag revokes definitions done with define. It recovers the previous definition if it exists.
Example
<undef uHTML bluestyle>macro
Overview
The macro tag allows to define complex new tags with own attributes within a uHTML file. The uHTML-code within the tag defined with the macro tag is interpreted. Definitions done with macro cannot be revoked like it can be done with definitions done with define, but they can be replaced if the replace attribute is supplied with the new definition.
Macros without own parameters can be used as variables in attributes.
Special Tag
<MacroBody>
The optional MacroBody tag within a macro definition marks the position of the body when the macro is deployed as a closed tag. If the macro is deployed as a not closed tag, MacroBody is ignored.
Attributes
name="MacroName"
The attribute name defines the name of the macro.
attributes="AttributeList"
The attribute attributes defines the valid attributes of the defined macro. The attributes of the macro are given in a comma separated list. It is possible to define default values for the macro attributes. Those default values are separated by a '=' from the attribute name. Leading and trailing spaces are ignored unless the value is included in single or double quotation marks. The value must not contain any comma.
replace
The attribute replace forces the replacement of a former macro definition with the same name. Without the attribute replace the definition get ignored if a macro with the same name exists.
Example
Definition:
<macro name="Label" attributes="text">
<div class="toplabel"><text></div>
</macro>Use:
<Label text="Home">Definition:
<macro name="Box" attributes="color,background=white">
<div class="boxclass" style="color:$color;background-color:$background">
<MacroBody>
</div>
</macro>Use:
<Box color="blue" background="#e3fff6">Boxtext</Box>defined
Overview
The defined tag content is included in the uHTML output if all attributes without a value equal to a name defined with define or macro or if the value of the attribute name contains a name defined either with define or with macro.
Attributes
name="name"
The name of the define or macro which should be tested for existence.
Example
<defined name="Count">
<Count>
</defined>notdefined
Overview
The notdefined tag content is included in the uHTML output if none of the attributes without a value equals to a name defined with define or macro or if the value of the attribute name do not contains a name defined either with define or with macro.
Attributes
name="name"
The name of the define or macro which should be tested for existence.
Example
<notdefined name="bluestyle">
<define bluestyle="color:blue;font-weight:bold;">
</notdefined>if
Overview
The tag if allows conditional content. It usually contains one ore more else tags which enclose alternative content.
Attributes
cond="clause"
The clause in the attribute cond decides if the content of the if tag is processed and passed to the http client. It is interpreted as a perl expression. It is true if the result is not 0 or it contains a string with a non-zero length. In the latter case the string need to be enclosed in quotation marks within the quotation marks of the attribute value.
If the attribute content evaluates 'true' the content of the tag is processed and passed on while the content of subordinated else-tags is ignored. In opposite case the tag content is discarded while the else tags get evaluated.
Example
<if cond="$File ne 'index.uhtml'">
<a href="/index.uhtml">Home</a>
</if>else
Overview
The tag else used within a if tag defines alternative content. If it contains the attribute cond, it's content get only processed and passed on if the clause in the attribute cond evaluates 'true'. In this case all other else tags within the parental if tag get discarded along with the content of the if tag.
Attributes
cond="clause"
The clause in the attribute cond decides if the content of the else tag is processed and passed to the http client. It is interpreted as a perl expression. It is true if the result is not 0 or it contains a string with a non-zero length. In the latter case the string need to be enclosed in quotation marks within the quotation marks of the attribute value.
If the attribute content evaluates 'true' the content of the tag is processed and passed on while the content of all other else tags within the parental if tags get discarded along with the content of the if tag.
Example
<if cond="$File ne 'index.uhtml'">
<a href="/index.uhtml">Home</a>
<else><img src="spacer.png" alt="placeholder"></else>
</if>choice
Overview
The deployment of if tags with an included else tag is always text-intensive. Sometimes just two tags or just two attribute values in some attributes of a tag make the difference. In such cases the tag choice is often the better alternative. The tag choice can be used as open or closed tag. The alternative values of the attributes need to be separated by "|". In case the clause in the attribute cond evaluates true, the value left of "|" is used, otherwise the value right of "|". If the value has a zero length, the attribute is omitted.
Attributes
cond="clause"
The clause in the attribute cond decides if the content on the left or the content on the right side of "|" in the attribute values is used. If no "|" is found in an attributes value, the value is used independent of the condition.
tag="ELEMENTNAME"
The attribute tag defines the name of the tag by which choice will be replaced. It is obligatory and in case it is missing or equals to a zero length string, the whole tag is omitted. It can contain two values separated by "|" which will be used according to the result of cond.
attr="AttributeList"
A comma separated list of attributes without values which have to be added to the tag. Two lists separated by "|" can be defined. The lists will be used according to the result of cond.
Example
<choice cond="'$ENV(HTTP_USER_AGENT)' =~ m/Explorer/" tag="div" class="explorer|normal">
....Text....
</choice>CondAttr
Overview
CondAttr drops all empty attributes. It is meant to avoid empty attributes which may confuse browsers.
Attributes
tag="ELEMENTNAME"
The attribute tag defines the name of the tag by which CondAttr will be replaced. It is obligatory and in case it is missing or equals to a zero length string, the whole tag is omitted.
Example
<CondAttr tag="div" class="$SpecialClass">
....Text....
</CondAttr>replace
Overview
The tag replace applies perl regular expressions to the text provided by the attribute text and inserts it into the HTML code. For more information on perl regular expressions, please consult the corresponding man page perlre.
Attributes
text="TEXT"
The text to be altered.
pattern="RegExPattern"
Patterns of the regular expression. Notice that backslashes "\" must be escaped (doubled) "\\".
replace="ReplaceText"
Text that will replace pattern. Notice that "$" signs must be escaped "\$".
options="OPTIONS"
Replace options. For more information about possible options please consult the perl regular expressions man page perlre.
Example
<replace text="$include(#data/products)" pattern="," replace="<br>">skipLF
Overview
The tag skipLF removes line feeds and any spaces and tabs following it, speak any spaces or tabs at the beginning of a line. It helps to keep the source code readable while allowing e.g. place images adjacent. It is especially useful with the tags macro and repeat.
Attributes
keepspaces
Remove line feeds only and keep all spaces.
allspaces
Remove spaces at the end of the lines as well.
tag="ELEMENTNAME"
If present, the attribute tag defines the name of a tag by which skipLF will be replaced. If it is missing or equals to a zero length string, the attribute is treated as not existent.
Example
<skipLF>
<img src="/img/left.gif">
<img src="/img/right.gif">
</skipLF>skipSpaces
Overview
Within the tag skipSpaces spaces, tabs and line feeds ahead and following any tag are removed. It helps to keep the source code readable while allowing e.g. place images adjacent. It is especially useful with the tags macro and repeat.
Attributes
tag="ELEMENTNAME"
If present, the attribute tag defines the name of a tag by which skipSpaces will be replaced. If it is missing or equals to a zero length string, the attribute is treated as not existent.
Example
<skipSpaces>
<img src="/img/left.gif">
<img src="/img/right.gif">
</skipSpaces>repeat
Repeat
Overview
The tag repeat repeats itself according to the values of it's attributes. The repeat tags can be nested. The variants repeat and Repeat are identical.
Attributes
list="ValueList"
A list of values separated by separator. The tag repeat is repeated once for each element of the list. If list is defined, other attributes are ignored.
separator="REGEX"
A regular expression used to split the list. If omitted the values in list must be separated by commas, colons or semicolons surrounded by optional (ignored) spaces (\s*[,;:]\s*).
sort
Valid only if the list attribute is given. If present, the list will be sorted alphabetically before the execution of repeat.
uniq
Valid only if the list attribute is given. If present, identical adjacent values of list are ignored. if the attribute sort is given, uniq is applied on the sorted list.
skipempty
Valid only if the list attribute is given. If present, empty list elements are ignored.
from="integer"
The attribute from defines the initial value to count the iterations. If not defined it defaults to 1.
If the attribute list is given, it defines the initial list element to be used. The first list element is referred by 1.
step="integer"
The attribute step defines the increment value for a iteration. It can have a negative value. If not defined it defaults to 1. It is ignored if the attribute list is given.
to="integer"
The attribute to defines the last value for a iteration. If not defined it defaults to 0. It is ignored if the attribute list is given.
count="integer"
The attribute to defines the count of iteration. If not defined it defaults to 0. It is ignored if to is defined and different from 0.
If the attribute list is given, it defines the count of elements to be used.
joint="text"
Text inserted between the repetitions of repeat. It can contain HTML tags. uHTML tags and variables will be ignored.
If uHTML tags and variables should get interpreted, the function $uHTMLtoHTML can be used.
Example
<center><repeat count="11" >#</repeat></center>RepeatCount
Overview
The tag RepeatCount is valid within the repeat tag. It returns the count of completed iterations of the tag repeat.
Example
<repeat count="20"><RepeatCount> completed<br></repeat>RepeatNum
Overview
The tag RepeatNum is valid within the repeat tag. It returns the number of the current iteration of the tag repeat.
Example
<repeat count="20">Am in iteration <RepeatNum><br></repeat>RepeatValue
Overview
The tag RepeatValue is valid within the repeat tag. It returns the current value associated the current iteration of the tag repeat. In case the overlying repeat tag has the attribute list, it returns the corresponding list value. Otherwise it returns the value calculated according to the attributes from and step of the overlying repeat tag.
Example
<repeat count="10">Line <RepeatValue><br></repeat>ListElement
Overview
The tag ListElement extracts an single element from a text list. It is ineffective and should be only used to occasionally extract a single list element and must be never used within a loop.
Attributes
list="LIST"
The list from which the element hast to be extracted. If missing or empty the tag is omitted.
nr="NUMBER"
Number of the element to be extracted. The first element in the list has the number 1. If missing or out of range the tag is omitted.
SEP="REGEX"
Element separator used in the list. If omitted it defaults to commas, colons or semicolons surrounded by optional (ignored) spaces (\s*[,;:]\s*).
Example
<ListElement list="A, B, C" nr="2">uFilePath
Overview
The tag uFilePath determines the absolute path of a file according to the uHTML path name conventions. Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.
Attributes
path="PATH"
Path to convert.
Example
Document Root: <uFilePath path="/">ENV
Overview
The tag ENV inserts the value of the environment variable name into the HTML-code.
Attributes
name="EnvVarName"
Name of the environment variable.
Example
<ENV name="SERVER_NAME">ENVkeys
Overview
The tag ENVkeys inserts a list of all environment variables names into the HTML-code.
Attributes
separator="SEPARATOR"
Separator between the names to be used in the list. Defaults to "," if omitted.
sort
If the attribute sort is present, the list is sorted.
Example
<ENVkeys>insert
Overview
The tag insert inserts the value of the attribute text into the HTML-code. The attribute raw prevents the interpretation of uHTML elements in text. This tag is used mainly for site debugging purposes.
Attributes
text="Text"
Text inserted into HTML.
= head4 raw
The attribute raw prevents the interpretation of uHTML elements in text.
Example
<insert text="$testfunc(A,1)">identity
Overview
The tag identity does literal nothing. This tag is used mainly for site debugging purposes.
Example
<identity>Text</identity>uModule
Overview
The tag uModule makes perl modules (usually uHTML modules) accessible within the website.
Attributes
path="FileName"
script="FileName"
module="FileName"
modules="FileName"
dir="FileName"
The filename of the required module. The attribute can contain several module names separated by commas. The file names are interpreted according to the uHTML file name conventions. Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.
error
The attribute error forces error messages in the servers log files.
Example
<uModule script="inc/edit/uHTML/edit.pm">
Attribute variables and functions provided by the std library
$defined(name)
Overview
The $defined function is used mainly within the cond attribute of different tags.
Parameters
name
The name of a definition either by define or by macro which should be tested for existence.
Example
<if cond="$defined(Products)">
<Products>
</if>$notdefined(name)
Overview
The $notdefined function is used mainly within the cond attribute of different tags.
Parameters
name
The name of a definition either by define or by macro which should be tested for existence.
Example
<include cond="$notdefined(Products)" file="#inc/products">$choice(cond,true,false)
Overview
Sometimes even the tag choice is to complex to choose between two alternative values for one attribute or two different attributes of the same tag need different values depending on different conditions for each attribute. For such cases the function $choice is defined.
Parameters
cond
Depending on the result of the clause in the parameter cond, either the value of the parameter true or the value of the parameter false is returned by the function choice.
true
Value returned if cond evaluates true.
false
Value returned if cond evaluates false.
Example
<div class="$choice($SiteName,std,special)">$Alternative(par1,par1,par3,…)
Overview
Sometimes the first true (in sense of perl) out of many values is needed. For such cases the function $Alternative is defined. $Alternative returns the first parameter which isn't an empty string or zero. To use it as a tag wrap it into the tag insert.
Parameters
par1,par1,par3,…
The first par* parameter which isn't an empty string or zero will be returned by the function Alternative.
Example
<insert text="$Alternative($FormData,$Default)">$AltText(par1,par1,par3,…)
Overview
Sometimes the first value containing some text out of many values is needed. For such cases the function $AltText is defined. $AltText returns the first parameter which isn't an empty string. To use it as a tag wrap it into the tag insert.
Parameters
par1,par1,par3,…
The first par* parameter which isn't an empty string will be returned by the function AltText.
Example
<insert text="$AltText($FormData,$Default)">$include(file,alt)
Overview
The function $include inserts the content of a file into a attribute. The file names are interpreted according to the uHTML file name conventions. Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.
Parameters
file
The parameter file defines the path and name of the included file. Wildcards * and ? are expanded according to glob rules and the included files get concatenated.
alt
In case no file defined by the file parameter is found, the file defined by the alt parameter get included. This parameter can be omitted.
Example
<select name="products">
<repeat list="$include(#data/products)">
<option><RepeatValue></option>
</repeat>
</select>$replace(text,pattern,replace,options)
Overview
The function $replace applies perl regular expressions to the text provided by the parameter text before returning it. For more information on perl regular expressions, please consult the corresponding man page perlre.
Parameters
text
The text to be altered.
pattern
Patterns of the regular expression. Notice that backslashes "\" must be escaped (doubled) "\\".
replace
Text that will replace pattern. Notice that "$" signs must be escaped "\$".
options
Replace options. For more information about possible options please consult the perl regular expressions man page perlre.
Example
<insert text="$replace('$include(#data/products)',',','<br>')">$RepeatCount()
Overview
The variable $RepeatCount is valid within the repeat tag. It returns the count of completed iterations of the tag repeat.
Example
<select name="weekday">
<repeat list="Monday,Tuesday,Wednesday,Thursday.Friday,Saturday,Sunday">
<option value="$RepeatCount"><RepeatValue></option>
</repeat>
</select>$RepeatNum()
Overview
The variable $RepeatNum is valid within the repeat tag. It returns the number of the current iteration of the tag repeat.
Example
<select name="weekday">
<repeat list="Monday,Tuesday,Wednesday,Thursday.Friday,Saturday,Sunday">
<option value="$RepeatCount"><RepeatNum>: <RepeatValue></option>
</repeat>
</select>$RepeatValue()
Overview
The variable $RepeatValue is valid within the repeat tag. It returns the current value associated the current iteration of the tag repeat, e.g. the corresponding value from the attribute list.
Example
<select name="weekday">
<repeat list="Monday,Tuesday,Wednesday,Thursday.Friday,Saturday,Sunday">
<option value="$RepeatNum"><RepeatValue></option>
</repeat>
</select>$ListElement(List,nr,SEP)
Overview
The variable $ListElement extracts an single element from a text list. It is ineffective and should be only used to occasionally extract a single list element and must be never used within a loop.
Parameters
list
The list from which the element hast to be extracted. If empty the result is an empty string.
nr
Number of the element to be extracted. The first element in the list has the number 1. If missing or out of range the result is an empty string.
SEP
Element separator used in the list. If omitted it defaults to \s*[,;:]\s*.
Example
<insert text="$ListElement( 'A, B, C',2 )">$uFilePath(path)
Overview
The function $uFilePath determines the absolute path of a file according to the uHTML path name conventions. Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.
Parameters
path
Path to convert.
Example
<if cond="-f '$uFilePath(/index.html)'"> <code>/index.html</code> exists. </if>$ENV(name)
Overview
The function $ENV inserts the value of the environment variable name into a attribute.
Parameters
name
Name of the environment variable.
Example
<if cond="'$ENV(HTTP_VIA)'"> Request passed a proxy server. </if>$ENVkeys(sort,separator)
Overview
The function $ENV inserts the value of the environment variable name into a attribute.
Parameters
sort
If true the list get sorted.
separator
Separator between the names to be used in the list. Defaults to "," if omitted.
Example
<repeat list="$ENVkeys(sort,';')">
<div><RepeatValue>=<ENV name="$RepeatValue"></div>
</repeat>$identity(value)
Overview
The function $identity does literal nothing. It just returns the unchanged parameter value. This tag is used mainly for site debugging purposes.
Parameters
value
The parameter value defines the return value of the function $identity.
Example
<insert text="$identity(Text)">$uHTMLtoHTML(uHTML) , =head3 Overview
The function $uHTMLtoHTML forces a parameter to be interpreted as uHTML input and be translated into HTML.
Parameters
uHTML
The parameter uHTML get translated into HTML.
Example
<skipLF>
<repeat count="20" joint="$uHTMLtoHTML(<RecordSeparator>)">
<Record num="$RepeatCount">
</repeat>
</skipLF>
perl functions provided by the uHTML::std library
uFilePath($path,$env)
Overview
The function uFilePath determines the absolute path of a file according to the uHTML path name conventions and the environment $env. Path names beginning with '/' are considered as relative to DOCUMENT_ROOT. Path names not beginning with '/' and not prefixed with '#' are considered as relative to the path of the current file. Path names prefixed with '#' are considered as file system absolute if a '/' follows the '#' and relative to DATA_ROOT (or the script directory) if no '/' follows the '#'.
Parameters
$path
Path to convert.
$env
Environment in which's context the path should be converted
Example
if(-f uFilePath('/index.html',$env)) {...SEE ALSO
perl(1), uHTML, http://www.uhtml.de/en/doc/std.uhtml
AUTHOR
Roland Mosler (Roland.Mosler@Place.Ug)
COPYRIGHT
Copyright 2009 Roland Mosler. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.