NAME

uHTML - user specific extension of HTML code

VERSION

Version 1.92

SYNOPSIS

A short example of a <include> tag using CGI (and apache). The function of the tag should be obvious. The example consists of two files, a perl-file and a uHTML-file. The perl-file implements the tag which is then used in the uHTML-file.

perl-file (CGI executable):

#!/usr/bin/perl

use uHTML;

sub Include($) {
  my $Node = shift;
  $Node->map(join('',<FH>),'') if $Node->attr('file') and
                                  open FH,$ENV{'DOCUMENT_ROOT'}.$Node->rawAttr('file');
}

uHTML::registerTag('include',\&Include);

#hook
open FILE,"$ENV{'DOCUMENT_ROOT'}$ENV{'PATH_INFO'}" or die "File: $ENV{'PATH_INFO'} not found";
print "Content-type: text/html\n\n";
print uHTML::recode(<FILE>);

This perl file can be broken up into two files, separating the definition of the tag from the cgi hook. By this the cgi hook open ... uHTML::recode can remain the same for several projects, while the library file is added to the cgi directory according to the requirement. Adequate named or located files are loaded automatic by the uHTML module. This allows to add html extensions according to a websites needs by copying of files without the intervention of a programmer.

Usage of the <include> tag:

uHTML-file:

<html>
...
<include file="/inc/headmetadata.txt">
...
</html>

DESCRIPTION

uHTML allows to extend HTML with user defined tags, extend standard HTML tags with new attributes and alter the behaviour of standard HTML tags and attributes. The server translates uHTML on the fly into HTML similar to PHP and other server side scripting languages. The main advantage of uHTML is following the HTML syntax allowing webdesigners not familiar with programming to use and edit uHTML tags in the same manner as HTML tags. Further uHTML makes copying of code snippets across of project files superfluous simplifying maintenance and increasing the robustness of code.

uHTML consists of two packages, uHTML itself and uHTMLnode which provides the recursive structure of a uHTML document. While uHTML is used to invoke the module, uHTMLnode provides the interface to the customized tag code.

========================

package uHTML

The uHTML package loads all modules from the script directory that match uHTML/*pm and that match *-uHTML.pm. It provides methods that assign code to tags and to tag attributes and invokes the uHTML to HTML translation.

Methods

uHTML::registerTagCode( $TagName,$Code ) ;

Bind the function $Code to the tags named $TagName. The function $Code will be called with a reference of the uHTML node corresponding to the tag $Code( $Node ). The function is expected to alter and adjust the tag attributes and content. The modified tag gets automatically inserted into the HTML output.

If more then one function is bound to one tag, the functions are daisy-chained. The execution order of those functions is not determined.

uHTML::registerTag( $TagName,$Code ) ;

Bind the function $Code to the tags named $TagName. The function $Code will be called with a reference of the uHTML node corresponding to the tag $Code( $Node ). The function is expected to insert necessary data using the appropriate uHTMLnode methods $node->map( $HeadText,$TailText ) or $node->insert().

uHTML::registerAttrCode( $VarName,$Code ) ;
uHTML::registerVar( $VarName,$Code ) ;

Bind the function $Code to the attribute variable called $VarName. Both functions are identical. The attribute variable gets replaced by the return value of the function.

The function $Code is called with a reference to the node representing the tag, the name of the attribute containing the function and the function name, followed by the function arguments: $Code( $Node,$Attribute,$Function,$Value1,$Value2, ... ).

uHTML::register( $Name,$Code ) ;

Bind the function $Code to the attribute variable called $Name and to a tag called $Name simultaneously. The tag or attribute variable gets replaced by the return value of the function.

If the function is called in reference to a tag, $Attribute and $Function are not defined. In this case the function if necessary has to set the values $Value1, $Value2, ..., from the attributes of the tag using $Node->Attr( $Name ).

uHTML::Tags() ;

Returns a list of all tags with a function assigned to.

uHTML::TestTag( $Name )

Check if some code is bound to the tag $Name.

uHTML::TestVar( $Name )

Check if some code is bound to the attribute variable $Name.

uHTML::fileStart

Set the current file name for debug output. Ignored in production mode.

uHTML::fileEnd

Reset the current file name for debug output to the previous name. Ignored in production mode.

uHTML::parse( $text,$env ) ;

Parses $text into a uHTML tree. Returns a reference to a uHTMLnode node. $env provides a reference to the environment. If not given, the current environment is used.

uHTML::recoded_list( $uhtml,$env ) ;

Translates uHTML data $uhtml into HTML. Returns a reference to a array of HTML chunks containing the final HTML code. $env provides a reference to the environment. If not given, the current environment is used.

uHTML::recode( $uhtml,$env ) = @_ ;

Translates uHTML data $uhtml into HTML. Depending on the context returns a scalar or string array containing the final HTML code. $env provides a reference to the environment. If not given, the current environment is used.

Production Mode and Debug Mode

uHTML produces some (sparse) error codes. It is advisable to switch them off in production mode. At the same time HTML comments get removed and the code get slightly compacted. The production mode is activated with $uHTML::FileName = '' ; prior to translation of uHTML to HTML.

========================

package uHTMLnode

The package uHTMLnode provides the hierarchical structure for the uHTML code and contains after the translation the HTML data.

Data Structure

uHTMLnode is only remotely related to the HTML nodes in DOM. The data structure is intended to be manipulated only by its methods.

# FirstChild: - first child node
# LastChild: - last child node
# Parent: - parent node
# Prev: - previous node (Null for the first node in a hierarchy level)
# Next: - following node (Null for the last node in a hierarchy level)
# Name: - name of the node (tag name)
# End: - true if the node has a closing counterpart (e.g. <div> ... </div>)
# XMLClose: - true if the node has no closing counterpart but is noted in XML manner with a "/" before the closing bracket (e.g. <img ..... />)
# Attributes: - reference to a HASH containing the attributes of a tag
# Text: - text within a node till the first child node or end of the node (corresponds to the first text node in DOM if the first DOM child node is a text node)
# Trailer: - text following a node (corresponds in DOM to the first text node following the node if the first following node is a DOM text node)
# tainted: - recursive processing of the node necessary
# HTML: - final HTML code
# ENV: - pointer to the current environment, decisive in FCGI environments

Methods

uHTMLnode->new( $Name,$Text,$Prev,$env ) ;

Create a new node with the name $Name, a trailing text $Text and the preceding node $Prev. This method is called by the uHTML package and is seldom needed outside of it.

$node->name() ;

The name of a node. It equals to the name of the uHTML tag represented by the node. By passing a argument $node->Name($NewName) the tag can be renamed.

$node->parent() ;

The parent node.

$node->prev() ;

The preceding node.

$node->next() ;

The following node.

$node->copy() ;

Copies a node. This function is useful to generate lists. The copy of the node is not hooked into the structure of the original uHTML file, although the parent node is correctly assigned. All child nodes are copied as well. The trailing text of the node is not included in the copy.

$node->prepend( $Node ) ;

Insert a node into the uHTML tree before current node.

$node->append( $Node ) ;

Insert a node into the uHTML tree after current node.

$node->embed( $Name ) ;

Creates a new node $Name and embeds the current node in it. In effect the current node gets replaced by the new node $Name while the current node becomes the only child of the new node.

$node->firstChild() ;

First subordinated node.

$node->lastChild() ;

Last subordinated node.

$node->addChild( $Child,$PrevChild ) ;

Add a child node after the child node $PrevChild. If $PrevChild is not defined, add as new first child node, if $PrevChild equals $node->lastChild() the new node becomes the new last child.

The node $Child mustn't be a child of $node. If $Child has its parent node set, it will be correctly moved within the uHTML document.

$node->appendChild( $Child ) ;

Add a child node as new last child.

The node $Child mustn't be a child of $node. If $Child has its parent node set, it will be correctly moved within the uHTML document.

$node->adoptChildren( $From,$Child ) ;

Transfer the children of one node to another.

The children of the node $From are moved to the $node and inserted if $Child is given after $Child or ahead of all children of $node if $Child is not defined.

$node->findChild( $Name,$Child ) ;

Find a child node of $node named $Name after the child $Child. If $Child is undefined, find first child node named $Name.

$node->replace( $New,$KeepTrailer ) ;

Replaces a node in the uHTML structure. Normally the trailing text gets replaced in process too. To keep it, $KeepTrailer must be true. Returns the detached original node if successful.

$node->detach( $KeepTrailer ) ;

Detaches a node from the uHTML structure. Normally the trailing text gets deleted in process. To keep it, $KeepTrailer must be true.

$node->delete() ;

Deletes a node from the uHTML structure.

$node->attr( $Name ) ;

The value of a singular attribute as a string. Possible attribute functions get interpreted. If more then one attribute with the same name exist, the values are concatenated. If a value get provided ($node->Attr( $Name,$Value ) ;), the attribute get set to this value. If the attribute do not exists, it gets created.

$node->rawAttr( $Name ) ;

The original value of a singular attribute as a string. Possible attribute functions are not interpreted. If more then one attribute with the same name exist, the values are concatenated. If a value get provided ($node->RawAttr( $Name,$Value ) ;), the attribute get set to this value. If the attribute do not exists, it gets created.

$node->codeAttr( $Name ) ;

The value of a singular attribute as a string. Possible attribute functions get interpreted. If more then one attribute with the same name exist, the values are concatenated.

$node->setAttr( $Name,$Value ) ;

Sets the attribute $Name to the $Value. If the attribute do not exists, it gets created.

$node->testAttr( $Name ) ;

Tests the existence of the attribute $Name. This is necessary to test for attributes without any value provided.

$node->testAnyAttr( $Name1,$Name2,$Name3, ,... ) ;

Tests the existence of any of the attributes with the provided names.

$node->testAllAttr( $Name1,$Name2,$Name3, ,... ) ;

Tests the existence of all attributes with the provided names.

$node->addAttr( $Name1,$Name2,$Name3, ,... ) ;

Creates the attributes $Name1, $Name2, $Name3, ,..., without assigning a value to them.

$node->deleteAttr( $Name1,$Name2,$Name3, ,... ) ;

Deletes the attributes $Name1, $Name2, $Name3, ,...

$node->attributes()

Reference to the attributes of a node. E.g. the style of a tag can be accessed by $node->attributes()->{'style'}. The methods above which access single attributes should be preferred.

$node->text() ;

The text inside of a closed tag up to the first child tag. It corresponds to the first text node in DOM if the first DOM child node is a text node. Can be altered by passing a argument.

$node->trailer() ;

The text following a tag up to the next tag. It corresponds in DOM to the first text node following the node if the first following node is a DOM text node. Can be altered by passing a argument.

$node->end() ;

True, if a tag is closed (the closing tag exists). If a argument is passed, the node becomes a closed node or open node depending on the argument.

$node->XMLClose() ;

True if the tag is closed by a "/>" instead of a simple ">". Can be enforced or removed by passing an according argument.

$node->map( $HeadText,$TailText ) ;

Map a node into HTML output without tags preceding the node with $HeadText and closing it with $TailText. If a node has no closing tag, $TailText follows directly $HeadText. Practically seen it replaces the opening and closing tags with $HeadText and $TailText. This is the most common way to produce HTML output in functions hooked into uHTML using uHTML::registerTag( $TagName,$Code ) ;.

$node->insert() ;

Inserts a node's HTML code including the tags and attributes. It is meant to insert an altered node into the HTML output. This is the second way to produce HTML output in functions hooked into uHTML using uHTML::registerTag( $TagName,$Code ) ;.

$node->HTML() ;

The HTML code of a node after a map() or insert() was performed. It is empty before a map() or insert() on the node is done. It is possible to set this value directly by passing an argument $node->HTML( $html ). By setting it the resulting HTML code is replaced by $html.

$node->appendText( $text ) ;

Append $text to the existing HTML output.

$node->env() ;

Returns a reference to the current environment in which a HTTP request is performed.

TODO

Port it to other languages. Make it faster.

BACKGROUND

While exploring problems connected to the integration of dynamic content into html documents in projects maintained by several people, it became apparent that any mixture of program and html code leads to charge conflicts between programmers and designers.

Extending and customizing html according to the requirements of a project while maintaining the familiar html syntax allows the html designer easy access to custom functions of a website. It leads to abatement of conflicts, errors, increases the readability of html documents and decreases the development time. The effect is specially reflected while the maintenance of a project where design improvements usually do not imply any action of the programmer and are sole done by the designer.

On the programmers side a consistent interface to the html tags leads to similar effects. uHTML == user-HTML connects basically each html tag with a code chunk allowing a manipulation of the html code before it leaves the http server. The strict assignment of functions to tags allows a high reusability of code. Indeed a set of customized tags can be included into a project by simply copying of the correlated module file into the project directory.

AUTHOR

Roland Mosler (Roland.Mosler@Place.Ug)

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install uHTMLnode, copy and paste the appropriate command in to your terminal.

cpanm

cpanm uHTMLnode

CPAN shell

perl -MCPAN -e shell
install uHTMLnode

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

perl-file (CGI executable):

uHTML-file:

DESCRIPTION

package uHTML

Methods

Production Mode and Debug Mode

package uHTMLnode

Data Structure

Methods

TODO

BACKGROUND

SEE ALSO

AUTHOR

COPYRIGHT

Module Install Instructions