Standard tags and functions for uHTML version 2.32

General Overview

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.

Terms of Use

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.

Requirements

This uHTML::std library do not require any other libraries but the main uHTML library.

 

List of uHTML tags provided by the uHTML::std library

include, define, undef, defined, notdefined, macro, if, else, choice, CondAttr, replace, skipLF, skipSpaces, repeat, RepeatCount, RepeatNum, RepeatValue, ListElement, uFilePath, ENV, ENVkeys, insert, identity, uModule

List of attribute variables and functions provided by the uHTML::std library

defined, notdefined, choice, Alternative, AltText, include, replace, RepeatCount, RepeatNum, RepeatValue, ListElement, uFilePath, ENV, ENVkeys, identity, uHTMLtoHTML,

List of perl functions provided by the uHTML::std library

uFilePath

 

 

uHTML tags provided by the uHTML::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 and is strongly advised to set it when including SVG files.
warn
The attribute warn without value triggers 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" >
up↑
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:

<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;">

Use:

<uHTML> <span style="$bluestyle"> is exciting </span>

up↑
undef

Overview

The undef tag revokes definitions done with define. It recovers the previous definition if it exists.

Example

<undef uHTML bluestyle>

up↑
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>

up↑
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>
up↑
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>
up↑
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>
up↑
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>
up↑
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>
up↑
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>
up↑
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>">
up↑
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>
up↑
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>
up↑
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>
up↑
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>
up↑
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>
up↑
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>
up↑
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">
up↑
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="/">
up↑
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">
up↑
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>
up↑
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.
raw
The attribute raw prevents the interpretation of uHTML elements in text.

Example

<insert text="$testfunc(A,1)">
up↑
identity

Overview

The tag identity does literal nothing. This tag is used mainly for site debugging purposes.

Example

<identity>Text</identity>
up↑
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">
up↑

Attribute variables and functions provided by the uHTML::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>
up↑
$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">
up↑
$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)">
up↑
$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)">
up↑
$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)">
up↑
$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>
up↑
$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>')">
up↑
$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>
up↑
$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>
up↑
$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>
up↑
$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 )">
up↑
$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>
up↑
$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>
up↑
$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>
up↑
$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)">
up↑
$uHTMLtoHTML(uHTML)
,

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>
up↑

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')) {...
up↑