/ 
PHTML-1.01
/ HTML::PHTML

NAME

HTML::PHTML - "Perl Embedded HTML" Page Cache

SYNOPSIS

use vars qw($PHTML $B);
require HTML::PHTML;

$B = '';
$PHTML = new HTML::PHTML("$FindBin::Bin/../lib/bm") if !$PHTML;
$PHTML->x($page_name);
print $B;

DESCRIPTION

This module is more useful when you also use FastCGI or Apache/mod_perl. If you are not using one of these packages yet, investigate that first.

Most HTML::* modules are wrappers around string manipulation. This module actually does something:

For each $page_name, the file $page_name.phtml is loaded from the given directory. The code is executed and HTML is appended to $B in the calling package. Optionally, per-page code is executed before any page is built.

This is much more general and easy than HTML::Embperl and does not need a separate binary like ePerl.

PAGE STRUCTURE

Raw HTML is copied as-is. Perl code can be embedded by quoting it with <: and :>. The open quote must be placed at the beginning of a line and the close quote is only recognized at the end of a line.

All of the perl code is evald in the same lexical block, so you may declare lexical variables or write for loops around the raw HTML. Also note that the eval happens in the caller's package so you can access all your usual globals and functions.

A few constructs are handled specially:

  • UNCAPTURED OUTPUT

    Normally, perl code is assumed to evaluate to a string to be immediately appended to the HTML buffer. However, if the code starts with a close brace, a my, or an ObjStore transaction (eg. try_read), then the value of the perl code is ignored.

  • REPLIES

    A block of embedded perl code that starts with an anonymous sub declaration is assumed to be a reply handler. You can use reply handlers to react a user response to an HTML form before the next page is generated.

    Normally, a reply handler should return false. However, if a handler redirects or generates the page itself, it should return true to stop the execution of subsequent handlers or the generation of the default next page.

EXAMPLE: DEMO.PHTML

 <body bgcolor="#ffffff" text="#000000" link="#000000" vlink="#000000" >
 <center><h1><big>
 <: small_caps("Mondo Server") :>
 </big></h1></center>
 <p>
 <hr><p>
 <font size=+2>With the help of these fantastic technologies,
 <div align=right>
 <: extern_href('<img src="/etc/perl_id_bw_sm.gif" border=0 >',
               'http://www.perl.org') :>
 <div align=left>
 <br>This sophisticated web application was written
 <div align=right>
 <: extern_href(qq(<img src="/etc/PoweredByOS.gif" border=0 >),
	       'http://www.odi.com') :>
 <div align=left>
 <br>In a mere <b>ten days</b>
 <div align=right>
 <: extern_href(qq(<img src="/etc/apache_logo.gif" border=0 >),
	       'http://www.apache.org') :>
 <div align=left>
 <br>With almost zero frustration!

 <: sub{
    if (is_cmd('login')) {
	my $loginUser = $p_in{'loginUser'};
	my $ok=0;
	try_update {
	    my $Users = $db->root('Users');
	    if (!exists $Users->{'index'}{$User}) {
		abort("'$User' is not a valid user.");
	    }
	    $u = $Users->{'index'}{$User};
	    $User = $u->name;
	    $ok=1;
	};
	die if ($@ and $@ !~ m/:abort:/);
	if ($ok) { return $PHTML->x('frameset'); }
    }
    0;
 } :>

BUGS

The parser should be slightly more customizable so we can factor out the ObjStore specific stuff.

Listen to REFERER to avoid running through all the reply handlers?

Avoid globals?

AUTHOR

Copyright (c) 1997 Joshua Nathaniel Pritikin. All rights reserved.

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

SEE ALSO

Apache/mod_perl or FastCGI, ObjStore, FindBin, and Experimental::Eval.