Standard tags and functions for uHTML version 1.5

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.

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 General Public License. The name of this library and it's author is to be named in all derivations.

Requirements

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

 

List of uHTML tags provided by the std library

include, define, undef, macro, defined, notdefined, if, else, choice, replace, skipLF, skipSpace, repeat, RepeatCount, RepeatValue, uFilePath, ENV, insert, identity, uModule

List of attribute variables and functions provided by the std library

defined, notdefined, choice, include, replace, RepeatCount, RepeatValue, uFilePath, ENV, identity

List of perl functions provided by the std library

uFilePath

 

 

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 the script directory if no '/' follows the '#'.

Attributes

file="FILEPATH"
The attribute 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="FILEPATH"
In case no file defined by the file attribute is found, the file defined by the alt attribute get included.
raw
The attribute raw without value prevents the interpretation of uHTML-elements in the included file.
nowarn
The attribute nowarn without value prevents 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 recovered when a definition done with define get revoked with undef unless the attribute replace is provided without a value.

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 only if name contains a tag or attribute 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 only if name contains a tag or attribute not defined neither with define nor 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 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 tags 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 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 included with 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↑
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.
replace="ReplaceText"
Text that will replace pattern.
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.

Example

<skipLF>
  <img src="/img/left.gif">
  <img src="/img/right.gif">
</skipLF>
up↑
skipSpace

Overview

Within the tag skipSpace 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.

Example

<skipSpace>
  <img src="/img/left.gif">
  <img src="/img/right.gif">
</skipSpace>
up↑
repeat

Overview

The tag repeat repeats itself according to the values of it's attributes.

Attributes

list="ValueList"
A comma, colon or semicolon separated list of values. The tag repeat is repeated once for each element of the list. If list is defined, other attributes are ignored.
from="integer"
The attribute from defines the initial value to count the iterations. If not defined it defaults to 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.
to="integer"
The attribute to defines the last value for a iteration. If not defined it defaults to 0.
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.

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

Overview

The tag 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

<repeat count="10">Line <RepeatValue><br><repeat>
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 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↑
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 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 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↑
$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 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.
replace
Text that will replace pattern.
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↑
$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="$RepeatValue"><RepeatValue></option>
  </repeat>
</select>
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 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↑
$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↑

perl functions provided by the std library

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 the script directory if no '/' follows the '#'.

Parameters

$path
Path to convert.

Example

if(-f uFilePath('/index.html')) {...
up↑