Delivering identical data

The content of the <head> section usually remains widely unaltered across all HTML files of a website. The vantage of keeping the constant part in a single separate file is obvious. To realize this with UHTML we need to create an <include> tag that inserts the content of one file called head-data into a html file. We assume that we have an include directory in our document root where we keep our overlapping chunks of HTML code in single files. Assuming UHTML is installed on our system, the UHTML file could then look like this:


      <include file="/include/head-data">

The functionality of the <include> tag is an asset in many projects. Following the mentioned naming convention proposal the perl code is placed in a file named include.pm located in the subdirectory UHTML of the script (CGI) directory. The file include.pm could then look like that:


  use uHTML ;

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


Linking with FCGI, Plack and nginx

Nginx serves only static files and expects an external server to handle dynamic content. UHTML works well with Plack over the FCGI interface. For this purpose UHTML must be installed system wide.

To link the small library above with our website a FCGI hook is needed. We place the necessary code in a file called uHTML.psgi in the script directory:


 use uHTML;
 use Encode;

   my $env  = shift ;
   my( $FILE,$DATA,$HTML,@HEAD,$LEN ) ;

   if( open $FILE,$env->{'PATH_TRANSLATED'} and
       $LEN = -s $FILE and
       read( $FILE,$DATA,$LEN ) == $LEN )
     $HTML = uHTML::recoded_list( $DATA,$env ) ;
     $LEN  = 0 ;
     $LEN += length Encode::encode( 'UTF-8',$_ )
        foreach @{$HTML} ;

     push @HEAD,'Content-Type','text/html; charset=UTF-8' ;
     push @HEAD,'Content-Length',$LEN ;
     push @HEAD,'x-powered-by','uHTML' ;
     return [ 200,\@HEAD, $HTML ] ;

   return [ 404,
            [ 'File Not Found' ]
          ] ;

Now we can start the FCGI server with plack using:

plackup -s FCGI -S /tmp/uHTML -a /srv/cgi-bin/uHTML.psgi

In the nginx configuration we add the section redirecting UHTML requests to our plackup server:

nginx configuration
location ~ \.uhtml$
  try_files $uri /index.uhtml =404 ;

  fastcgi_keep_conn on ;
  fastcgi_split_path_info ^()(.*uhtml)$;

  fastcgi_pass   unix:/tmp/uHTML ;
  fastcgi_index  index.uhtml;

  fastcgi_param  URI                  $uri;
  fastcgi_param  SCRIPT_FILENAME
  fastcgi_param  SCRIPT_NAME          $fastcgi_script_name;
  fastcgi_param  PATH_TRANSLATED
  fastcgi_param  QUERY_STRING         $query_string;
  fastcgi_param  REQUEST_METHOD       $request_method;
  fastcgi_param  CONTENT_TYPE         $content_type;
  fastcgi_param  CONTENT_LENGTH       $content_length;
  fastcgi_param  REQUEST_URI          $request_uri;
  fastcgi_param  REQUEST              $request;
  fastcgi_param  REQUEST_SCHEME       $scheme ;
  fastcgi_param  REQUEST_FILE         $request_filename;
  fastcgi_param  DOCUMENT_URI         $document_uri;
  fastcgi_param  DOCUMENT_ROOT        $document_root;
  fastcgi_param  SERVER_PROTOCOL      $server_protocol;
  fastcgi_param  GATEWAY_INTERFACE    CGI/1.1;
  fastcgi_param  SERVER_SOFTWARE      nginx/$nginx_version;
  fastcgi_param  REMOTE_ADDR          $remote_addr;
  fastcgi_param  REMOTE_PORT          $remote_port;
  fastcgi_param  SERVER_ADDR          $server_addr;
  fastcgi_param  SERVER_PORT          $server_port;
  fastcgi_param  SERVER_NAME          $server_name;
  fastcgi_param  HOST_NAME            $hostname;
  fastcgi_param  HTTPS                $https;
  fastcgi_param  HTTP_COOKIE          $http_cookie;
  fastcgi_param  HTTP_ACCEPT_LANGUAGE $http_accept_language;
  fastcgi_param  REDIRECT_STATUS      200;
  fastcgi_param  SCRIPT_ROOT          /srv/cgi-bin ;
  fastcgi_param  DATA_ROOT            /srv/cgi-bin ;

location /

Linking with CGI and Apache

On systems with Apache and CGI UHTML can be installed in two ways, system-wide or website local. System-wide installation is preferred, it makes UHTML available for all websites hosted on the system, but needs root privileges. Website local installation is possible without root privileges. It provides UHTML just for the particular site.

To link the small library above with our website a CGI hook is needed. We place the necessary code in a file called uhtml.pl in the script directory:



  use uHTML;

   or die "File: $ENV{'PATH_INFO'} not found";
  print uHTML::recode(join('',<$FILE>));

To get the functionality “magically” into all *.uhtml files, we add some lines into the .htaccess file in our DOCUMENT_ROOT :

  DirectoryIndex index.uhtml
  RewriteEngine on
  RewriteRule ^(/?)(.*\.uhtml) $1cgi-bin/uhtml.pl/$2 [L,QSA]

This full working example shows just the basic principle how to add an user-tag into a website using UHTML . It do not show the use of attribute functions or request initialisation, but including any of this two is trivial.

  • Example with all files and directories as needed by apache:

    Complete uHTML Example uHTML Example (10.47kB, from 06.07.2021, 12:34:05)


German Version

Other Sites:
