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.
This documentation refers to the version 2.32 of the uHTML::std library.
To install the module project local, copy it into the uHTML subdirectory of the
script-directory of the website. To install it globally, copy it into the uHTML
subdirectory of a perl-library directory.
It is allowed to use this library under the actual GNU Lesser General Public License. The name of this library and it's author is to be named in all derivations.
This uHTML::std library do not require any other libraries but the main uHTML library.
uHTML::std libraryinclude, define, undef, defined, notdefined, macro, if, else, choice, CondAttr, replace, skipLF, skipSpaces, repeat, RepeatCount, RepeatNum, RepeatValue, ListElement, uFilePath, ENV, ENVkeys, insert, identity, uModule
uHTML::std librarydefined, notdefined, choice, Alternative, AltText, include, replace, RepeatCount, RepeatNum, RepeatValue, ListElement, uFilePath, ENV, ENVkeys, identity, uHTMLtoHTML,
uHTML::std library
uHTML::std libraryThe 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.
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 '#'.
file="FILEPATH"
file defines the path and name of the included file.
files="FILEPATH"
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"
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
raw without value prevents the interpretation of
uHTML-elements in the included file. It should be used if files without
uHTML-elements get included and is strongly advised to set it when including
SVG files.
warn
warn without value triggers error messages in case
the included file isn't found or is not readable.
cond="clause"
cond attribute is optional. If present, then the include
tag is executed only if the clause in the attribute cond evaluates 'true'.
file="/include/navigation" >
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.
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.
createonly
createonly without any value is supplied,
only new definitions will be regarded. Existing definitions will be skipped.
replace
replace without any value is supplied,
the last definition of a tag and variable will be replaced
not recoverable by undef.
<define uHTML='<span
style="font-family:serif;color:#34a;">
<span style="font-weight:bold;color:#fe6f02;
font-size:0.8em">U</span>HTML</span>'
bluestyle="color:blue;font-weight:bold;">
<uHTML> <span
style="$bluestyle">
is exciting </span>
The undef tag revokes definitions done with define. It recovers the previous definition if it exists.
<undef uHTML bluestyle>
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.
<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.
name="MacroName"
name defines the name of the macro.
attributes="AttributeList"
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
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.
<macro name="Label"
attributes="text">
<div
class="toplabel"><text></div>
</macro>
<Label text="Home">
<macro name="Box"
attributes="color,background=white">
<div class="boxclass"
style="color:$color;background-color:$background"
>
<MacroBody>
</div>
</macro>
<Box color="blue"
background="#e3fff6">Boxtext</Box>
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.
name="name"
name="Count">
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.
name="name"
name="bluestyle">bluestyle="color:blue;font-weight:bold;">The tag if allows conditional content. It usually contains one ore more else tags which enclose alternative content.
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.
'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.
cond="$File ne 'index.uhtml'">
href="/index.uhtml">Home</a>
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.
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.
'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.
cond="$File ne 'index.uhtml'">
href="/index.uhtml">Home</a>src="spacer.png"
alt="placeholder"></else>
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.
cond="clause"
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"
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"
"|" can be defined. The lists will be used according
to the result of cond.
cond="'$ENV(HTTP_USER_AGENT)' =~ m/Explorer/"
tag="div"
class="explorer|normal">CondAttr drops all empty attributes. It is meant to avoid empty attributes which may confuse browsers.
tag="ELEMENTNAME"
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.
tag="div"
class="$SpecialClass">
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.
text="TEXT"
pattern="RegExPattern"
replace="ReplaceText"
pattern. Notice that
"$" signs must be escaped "\$".
options="OPTIONS"
text="$include(#data/products)"
pattern=","
replace="<br>">
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.
keepspaces
allspaces
tag="ELEMENTNAME"
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.
src="/img/left.gif">src="/img/right.gif">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.
tag="ELEMENTNAME"
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.
src="/img/left.gif">src="/img/right.gif">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.
list="ValueList"
separator. The tag repeat is repeated
once for each element of the list. If list is defined, other attributes
are ignored.
separator="REGEX"
list. If omitted the values in
list must be separated by commas, colons or semicolons surrounded
by optional (ignored) spaces (\s*[,;:]\s*).
sort
list attribute is given.
If present, the list will be sorted alphabetically
before the execution of repeat.
uniq
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
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.
list is given, it defines the initial list
element to be used. The first list element is referred by 1.
step="integer"
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"
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.
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.
count="11"
>#</repeat></center>
The tag RepeatCount is valid within the repeat tag. It returns the count of completed iterations of the tag repeat.
count="20"><RepeatCount>
completed<br></repeat>
The tag RepeatNum is valid within the repeat tag. It returns the number of the current iteration of the tag repeat.
count="20">Am in iteration <RepeatNum><br></repeat>
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.
count="10">Line
<RepeatValue><br></repeat>
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.
list="LIST"
nr="NUMBER"
1.
If missing or out of range the tag is omitted.
SEP="REGEX"
\s*[,;:]\s*).
list="A, B, C"
nr="2">
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 '#'.
path="PATH"
path="/">
The tag ENV inserts the value of the environment variable name
into the HTML-code.
name="EnvVarName"
name="SERVER_NAME">
The tag ENVkeys inserts a list of all environment variables names into the HTML-code.
separator="SEPARATOR"
," if omitted.
sort
sort is present, the list is sorted.
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.
text="Text"
raw
raw prevents the interpretation
of uHTML elements in text.
text="$testfunc(A,1)">
The tag identity does literal nothing. This tag is used mainly for site debugging purposes.
The tag uModule makes perl modules (usually uHTML modules) accessible within the website.
path="FileName"script="FileName"module="FileName"modules="FileName"dir="FileName"'/' 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
error forces error messages
in the servers log files.
script="inc/edit/uHTML/edit.pm">
uHTML::std library
The $defined function is used mainly within the cond attribute of different tags.
name
cond="$defined(Products)">
The $notdefined function is used mainly within the cond attribute of different tags.
name
cond="$notdefined(Products)" file="#inc/products">
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.
cond
cond, either the value of the
parameter true or the value of the parameter false is
returned by the function choice.
true
cond evaluates true.
false
cond evaluates false.
class="$choice($SiteName,std,special)">
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.
par1,par1,par3,…
par* parameter which isn't an empty string or zero
will be returned by the function Alternative.
text="$Alternative($FormData,$Default)">
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.
par1,par1,par3,…
par* parameter which isn't an empty string
will be returned by the function AltText.
text="$AltText($FormData,$Default)">
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 '#'.
file
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
file parameter is found, the file
defined by the alt parameter get included. This parameter can be omitted.
name="products">list="$include(#data/products)">
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.
text
pattern
replace
pattern. Notice that
"$" signs must be escaped "\$".
options
text="$replace('$include(#data/products)',',','<br>')">
The variable $RepeatCount is valid within the repeat tag. It returns the count of completed iterations of the tag repeat.
name="weekday">list="Monday,Tuesday,Wednesday,Thursday.Friday,Saturday,Sunday">value="$RepeatCount"><RepeatValue></option>The variable $RepeatNum is valid within the repeat tag. It returns the number of the current iteration of the tag repeat.
name="weekday">list="Monday,Tuesday,Wednesday,Thursday.Friday,Saturday,Sunday">value="$RepeatCount"><RepeatNum>:
<RepeatValue></option>
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.
name="weekday">list="Monday,Tuesday,Wednesday,Thursday.Friday,Saturday,Sunday">value="$RepeatNum"><RepeatValue></option>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.
list
nr
1.
If missing or out of range the result is an empty string.
SEP
\s*[,;:]\s*.
text="$ListElement( 'A, B, C',2 )">
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 '#'.
path
cond="-f '$uFilePath(/index.html)'">
<code>/index.html</code> exists.
</if>
The function $ENV inserts the value of the environment variable name
into a attribute.
name
cond="'$ENV(HTTP_VIA)'">
Request passed a proxy server.
</if>
The function $ENV inserts the value of the environment variable name
into a attribute.
sort
separator
," if omitted.
list="$ENVkeys(sort,';')">name="$RepeatValue"></div>
The function $identity does literal nothing.
It just returns the unchanged parameter value.
This tag is used mainly for site debugging purposes.
value
value defines the return value of the
function $identity.
text="$identity(Text)">
The function $uHTMLtoHTML forces a parameter to be interpreted as uHTML input and be translated into HTML.
uHTML
uHTML get translated into HTML.
count="20"
joint="$uHTMLtoHTML(<RecordSeparator>)">num="$RepeatCount">uHTML::std library
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 '#'.
$path
$env
(-f uFilePath('/index.html')) {...