WEBDYNE(3)

NAME
WebDyne - create web pages with embedded Perl

SYNOPSIS

 # Example 1. Available syntaxes for embedding Perl code in HTML using WebDyne.
 #
 <html><body><pre>
 Hello World time is: <perl> localtime() </perl>
 Hello World time is: <? localtime() ?>
 Hello World time is !{! localtime() !}
 # Example 2. Calling a Perl subroutine located at the end of the HTML file.
 #
 <html><body><pre>
 Hello World time is: <? &gettime ?>
 </pre></body></html>
 __PERL__
 sub gettime { localtime() }
 # Or
 #
 <html><body><pre>
 Hello World time is: <perl method="gettime"/>
 </pre></body></html>
 __PERL__
 sub gettime { localtime() }
 # Example 3. Rendering text or HTML with embedded variables from Perl block.
 #
 <html><body><pre>
 <perl method=gettime>
 Hello World time is ${timenow}
 </perl>
 __PERL__
 sub gettime {
     my $self=shift();
     my $time=localtime();
     $self->render( timenow=>$time )
 }
 # Example 4 - using CGI.pm pseudo-tags and array, hash values and Perl attributes.
 #
 <start_html title="Example">
 <start_form>
 <popup_menu name=foo values="@{1,2}">
 <popup_menu name=bar values="%{red=>red, blue=>blue}">
 <popup_menu name=baz values="!{! my @val=(3,4); \@val !}">
 <submit>
 You chose foo=+{foo}, bar=+{bar}, baz=+{baz}
 # Example 5 - Blocks 1
 #
 <start_html>
 <perl method="greeting"/>
 <block name="morning">
 Good Morning
 </block>
 <block name="afternoon">
 Good Afternoon
 </block>
 __PERL__
 sub greeting {
   my $self=shift();
   if ([localtime]->[2] > 12) { $self->render_block("afternoon") }
   else { $self->render_block("morning") }
 }

 # Example 6 - Blocks 2
 #
 <start_html>
 <perl method="greeting">
 What a fine day. I say unto you at ${timenow}:
 <block name="morning">
 Good Morning
 </block>
 <block name="afternoon">
 Good Afternoon
 </block>
 </perl>
 __PERL__
 sub greeting {
   my $self=shift();
   if ([localtime]->[2] > 12) { $seld->render_block("afternoon") }
   else { $self->render_block("morning") }
   $self->render( timenow=>scalar localtime );
 }

 # Example 7 - CGI forms and params
 #
 <start_html>
 <start_form>
 <popup_menu name=foo values="@{1,2}">
 <popup_menu name=bar values="@{3,4}">
 <submit>
 <end_form>
 <perl method="result">
 You chose option foo:${foo} bar:${bar}
 </perl>
 __PERL__
 sub result {
   my $self=shift();
   # Simple
   my $foo=$_{"foo"};
   # Longer
   my $CGI=$self->CGI();
   my $bar=$CGI->param("bar");
   return $self->render( foo=>$foo, bar=>$bar )
 }

DESCRIPTION

WebDyne is a Perl based dynamic HTML engine. It works with web servers (or from the command line) to render HTML documents with embedded Perl code.

Once WebDyne is installed and initialised to work with a web server, any file with a .psp extension is treated as a WebDyne source file. It is parsed for WebDyne or CGI.pm pseudo-tags (such as <perl> and <block> for WebDyne, or <start_html>, <popup_menu> for CGI.pm) which are interpreted and executed on the server. The resulting output is then sent to the browser.

Pages are parsed once, then optionally stored in a partially compiled format - speeding up subsequent processing by avoiding the need to re-parse a page each time it is loaded. WebDyne works with common web server persistant/resident Perl modules such as mod_perl and FastCGI to provide fast dynamic content.

DOCUMENTATION

This man page containes only a subset of information about how to use the WebDyne module. For more complete information and examples see the documentation at http://webdyne.org[1]

INITIALISATION

Web servers must be configured to pass .psp pages to the WebDyne module for processing. WebDyne comes with an installer for the Apache web server, wdapacheinit, which will modify the Apache configuration files appropriately. Installers for selected other web servers are available separately from CPAN. If you do not wish to run wdapacheinit - or it does not work as expected - the following is a minimal Apache 2.x config file (which assumes you already have mod_perl installed and activated in Apache)

     PerlModule      WebDyne
     AddHandler      perl-script     .psp
     PerlHandler     WebDyne

This is a bare-bones config which does not enable such features as caching - see the documentation located at http://webdyne.org for further configuration details for Apache and other web servers.

EMBEDDING PERL INTO HTML

Perl can be embedded into HTML in one of two ways - inline intermingled with HTML, or at the end of the HTML document (non-inline).

Inline Perl

Inline code is intermingled within the HTML code and can be triggered using one of three syntaxes:

    1. Between <perl> .. </perl> tags

    2. Betwen Processing Instruction (PI) <? .. ?> tags

    3. Between a custom curly brace !{! .. !} syntax

Example:

     <html><body><pre>
     Hello World time is: <perl> localtime() </perl>
     Hello World time is: <? localtime() ?>
     Hello World time is !{! localtime() !}

All of these syntax alternatives are equivalent, however the curly brace format !{! .. !} has the advantage of working everywhere, including in standard HTML tag attributes, e.g.:

     <html><body><pre>
     <img src="!{! &img_height("foo.jpg") !}" width=...

    Important

    Any embedded Perl code must return a non-null value - i.e. it must return something. If you want the Perl code to run without rendering any output then return a reference to undef, e.g.:

         # These are OK
         #
         <perl> &do_something; return "Done !"</perl>
         <perl> &do_nothing; return \undef </perl>
         # These are not
         #
         <perl> ...; return undef; </perl>
         <perl> ...; return 0 </perl>
         <perl> ...; return "" </perl>

non-Inline Perl

Non-inline code is Perl code located either in an external module (e.g. Country::Locale), or at the bottom of the HTML document in a special __PERL__ section that is not intermingled within the HTML of the page. Non-inline Perl is called when a method attribute is supplied with a perl tag. Example:

     <html><body>
     <perl method="Foo::Bar::baz"/> # Assumes Foo::Bar is available in @INC path

Calling a method in a __PERL__ block at the end of the document

     <html><body>
     <perl method="hello"/>
     World
     __PERL__
     sub hello { return "Hello" }

Passing parameters to Perl

You can pass parameters to a Perl routine:

     #  Pass param to inline Perl - not that useful
     #
     <perl param="foo">
       my $self=shift;     #  First param is always self ref to WebDyne object
       my $param=shift;    #  Tag attribute params, i.e. "foo" in this case.
       if ($param eq "foo") { do something
       ...
     </perl>
     #  Pass params to non-inline Perl - very useful
     #
     <perl method="display_image" param="foo.jpg/>
     Above is a picture of the mysterious foo object
     ..
     <perl method="display_image" param="bar.jpg/>
     And here we have the equally enegmatic bar subspecies
     ..
     __PERL__
     sub display_image {
       my $self=shift;    #  Self ref
       my $image=shift;   #  Param passed to perl routine as per param attriute
     #  Also possible to pass array or hash references (see later)
     <perl method="foo" param="@{1,2}">  # Pass array ref
     <perl method="foo" param="%{a=>1, b=>2}"> # Pass hash ref.

BLOCKS

Blocks are discrete chunks of HTML code located within the document which may be rendered (multiple times if needed) or left invisible. There are two types of blocks available on a WebDyne page:

Within non-Inline Perl tags a block is implicit. e,g,:

     <perl method="agent">
     Time to upgrade ?
     </perl>
     __PERL__
     sub agent {
       my $self=shift();
       if ($ENV{"HTTP_USER_AGENT"}=~/Mosaic/i) {
         return $self->render(); # Print what's between the <perl>..</perl> tags
       else {
         return \undef; # Don't print anyting "Time to upgrade ?" will not be seen.
       }
     }

Or a block can be declared explicitly with the <block> .. </block> tags:

     <perl>
       my $self=shift();
       if ((my $agent=$ENV{"HTTP_USER_AGENT"})=~/Explorer/i) {
         $self->render_block("ie");
       }
       elsif ($agent=~/Firefox/) {
         $self->render_block("firefox")
       }
     </perl>
     ..
     <block name="ie">
       Welcome IE User
     </block>
     <block name="firefox">
       Welcome Netscape User
     </block>

    Note

    blocks should be declared after the Perl code that renders them - e.g. the following will not work:

         <block name="foo">
         Hello World
         </block>
         <perl> shift()->render_block("foo") </perl>

VARIABLES AND SUBSTITUTION

Text within <perl> and <block> tags can be modified by the use of variables. Standard scalar variables are represented by the syntax ${varname}, and are populared bt paramaters supplied to the render and render_block methods. E.g.:

     #  Within a perl block
     <perl method="hello">
     Hello World, the time is ${timenow}
     <perl>
     __PERL__
     sub hello {
       my $self=shift();
       $self->render( timenow=>scalar localtime }
     }
     #  Within a named block
     #
     <perl method="hello"/>
     <block name="foo">
     Hello World, the time is ${timenow}
     </block>
     __PERL__
     sub hello {
       my $self=shift();
       $self->render_block( "foo", timenow=>scalar locatime );
     }

Other variables/substitutions available:

    • @{var,var,..} for arrays, e.g. @{"foo", "bar"}

    • %{key=>value, key=>value, ..} for hashes e.g. %{ a=>1, b=>2 }

    • +{varname} for CGI form parameters, e.g. +{firstname}

    • *{varname} for environment variables, e.g. *{HTTP_USER_AGENT}

    • ^{requestmethod} for Apache request ($r=Apache->request) object methods, e.g. ^{protocol}. Only available for in Apache/mod_perl, and only useful for request methods that return a scalar value

Some examples:

     <start_html>
     <start_form>
     <popup_menu name="foo" values="@{ 1,2 }">
     <popup_menu name="bar" values="%{ 1=>red, 2=>blue }">
     <submit>
     <end_form>
     Your results:
     <pre>
     You chose values +{foo} and +{bar}
     Your user agent is *{HTTP_USER_AGENT}
     Your request protocol is ^{protocol}

INTEGRATION WITH CGI.PM

Any CGI.pm method that generates HTML tags or code can be used as a pseudo-tag,e.g:

     <start_html> # From CGI.pm
     <start_form>
     <popup_menu name="foo">
     <textfield name="bar" size="20">
     <submit>
     <end_form>

WEBDYNE TAGS REFERENCE

Reference of WebDyne tags and supported attributes

<perl>
    Run Perl code either in-line (between the <perl>..</perl>) tags, or non-inline via the method attribute

    method=[Module::Name::]method
        Optional. Call an external perl subroutine in a pre-loaded module, or a subroutine in a __PERL__ block at the end of the HTML file

    param=scalar|array|hash
        Optional. Parameters to be supplied to perl routine. Supply array and hash using @{1,2} and %{a=>1, b=>2} conventions respectively.

    static=1
        Optional. This Perl code to be run once only and the output cached for all subsequent requests.

<block>
    Block of HTML code to be optionally rendered if desired by call to render_block Webdyne method.

    name=identifier
        Mandatory. The name for this block of HTML. You can have more than one block with the same name - all blocks matching the name supplied to render_block will be displayed.

    display=1
        Optional. Force display of this block even if not invoked by render_block WebDyne method. Useful for prototyping.

    static=1
        Optional. This block rendered once only and the output cached for all subsequent requests

<include>
    Include HTML or text from an external file. Include sections are static by default - they are loaded once at compile time and not refreshed until the Perl process (e.g. Apache) is restarted.

    file=filename
        Mandatory. Name of file we want to include. Can be relative to current directory or absolute path.

    head=1
        Optional. File is an HTML file and we want to include just the <head> section

    body=1
        Optional. File is an HTML file and we want to include just the <body> section.

    block=blockname
        Optional. File is a .psp file and we want to include a <block> section from that file.

<dump>
    Display CGI paramters in dump format via CGI->Dump call. Useful for debugging. Only rendered if $WEBDYNE_DUMP_FLAG global set to 1 in WebDyne constants (see below)

    display=1
        Optional. Force display even if $WEBDYNE_DUMP_FLAG global not set. Useful when debugging a single page.

WEBDYNE API REFERENCE

When running Perl code within a WebDyne page the very first parameter passed to any routine (in-line or in a __PERL__ block) is an instance of the WebDyne page object (referred to as $self in most of the examples). All methods return undef on failure, and raise an error using the err() function. The following methods are available to any instance of the WebDyne object:

CGI()
    Returns an instance of the CGI.pm object for the current request.

r(), request()
    Returns an instance of the Apache request object if running under mod_perl, or a reference to an WebDyne::Request::Fake instance if not running under Apache/mod_perl.

render( key=>value, key=>value, .. )
    Called to render the text or HTML between <perl>..</perl> tags. Optional key and value pairs will be substituted into the output as per the variable section. Returns a scalar ref of the resulting HTML.

render_block( blockname, key=>value, key=>value, ..).
    Called to render a block of text or HTML between <block>..</block> tags. Optional key and value pairs will be substituted into the output as per the variable section. Returns scalar ref of resulting HTML if called with from <perl>..</perl> section containing the block to be rendered, or true (\undef) if the block is not within the <perl>..</perl> section (e.g. further into the document, see the block section for an example).

redirect({ uri=>uri | file=>filename | html=>\html_text })
    Will redirect to URI or file nominated, or display only nominated text. Any rendering done to prior to this method is abandoned.

cache_inode( seed )
    Returns the page unique ID (UID). Called inode for legacy reasons, as that is what the UID used to be based on. If a seed value is supplied a new UID will be generated based on an MD5 of the seed. Seed only needs to be supplied if using advanced cache handlers.

cache_mtime( uid )
    Returns the mtime (modification time) of the cache file associated with the optionally supplied UID. If no UID supplied the current one will be used. Can be used to make cache compile decisions by WebDyne::Cache code (e.g if page > x minutes old, recompile).

cache_compile( )
    Force recompilation of cache file. Can be used in cache code to force recompilation of a page, even if it is flagged static. Returns current value if no parameters supplied, or sets if parameter supplied.

no_cache()
    Send headers indicating that the page is not be cached by the browser or intermediate proxies. By default WebDyne pages automatically set the no-cache headers, although this behaviour can be modified by clearing the $WEBDYNE_NO_CACHE variable and using this function

meta()
    Return a hash ref containing the meta data for this page. Alterations to meta data are persistent for this process, and carry across Apache requests (although not across different Apache processes)

WEBDYNE GLOBAL CONSTANTS

Constants can be set to modify the behaviour of the WebDyne module. Constants can be set in Apache (via the PerSerVar directive), in a system file (/etc/webdyne.pm in *nix, %WINDIR%/webdyne.pm in Windows) or via environment variables. See the documentation at webdyne.org for specific examples of how to set these variables The following constants are available:

$WEBDYNE_CACHE_DN
    The name of the directory that will hold partially compiled WebDyne cache files. Must exist and be writable by the Apache process

$WEBDYNE_STARTUP_CACHE_FLUSH_DN
    Remove all existing disk cache files at Apache startup. 1=yes (default), 0=no. By default all disk cache files are removed at startup, and thus pages must be recompiled again the first time they are viewed. If you set this to 0 (no) then disk cache files will be saved between startups and pages will not need to be re-compiled if Apache is restarted.

$WEBDYNE_CACHE_CHECK_FREQ
    Check the memory cache after this many request (per-process counter). default=256. After this many requests a housekeeping function will check compiled pages that are stored in memory and remove old ones according to the criteria below.

$WEBDYNE_CACHE_HIGH_WATER
    Remove compiled from pages from memory when we have more than this many. default=64

$WEBDYNE_CACHE_LOW_WATER
    After reaching HIGH_WATER delete until we get down to this amount. default=32

$WEBDYNE_CACHE_CLEAN_METHOD
    Clean algorithm. default=1, means least used cleaned first, 0 means oldest last view cleaned first

$WEBDYNE_EVAL_SAFE
    default=0 (no), If set to 1 means eval in a Safe.pm container.

$WEBDYNE_EVAL_SAFE_OPCODE_AR
    The opcode set to use in Safe.pm evals (see the Safe man page). Defaults to "[:default]". Use [&Opcode::full_opset()] for the full opset. CAUTION Use of WebDyne with Safe.pm not comprehensively tested.

$WEBDYNE_EVAL_USE_STRICT
    The string to use before each eval. Defaults to "use strict qw(vars);". Set to undef if you do not want strict.pm. In Safe mode this becomes a flag only - set undef for "no strict", and non-undef for "use strict" equivalence in a Safe mode (checked under Perl 5.8.6 only, results in earlier versions of Perl may vary).

$WEBDYNE_STRICT_VARS
    Check if a var is declared in a render block (e.g $ {foo}) but not supplied as a render parameter. If so will throw an error. Set to 0 to ignore. default=1

$WEBDYNE_DUMP_FLAG
    If 1, any instance of the special <dump> tag will print out results from CGI->dump(). Use when debugging forms. default=0

$WEBDYNE_DTD
    The DTD to place at the top of a rendered page. Defaults to: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

$WEBDYNE_HTML_PARAM
    Default attributes for the <html> tag, e.g. { lang =>"en-US" }. undef by default

$WEBDYNE_COMPILE_IGNORE_WHITESPACE
    Ignore source file whitespace as per HTML::TreeBuilder ignore_ignorable_whitespace function. Defaults to 1

$WEBDYNE_COMPILE_NO_SPACE_COMPACTING
    Do not compact source file whitespace as per HTML::TreeBuilder no_space_compacting function. Defaults to 0

$WEBDYNE_STORE_COMMENTS
    By default comments are not rendered. Set to 1 to store and display comments from source files. Defaults to 0

$WEBDYNE_NO_CACHE.
    WebDyne should send no-cache HTTP headers. Set to 0 to not send such headers. Defaults to 1

$WEBDYNE_DELAYED_BLOCK_RENDER
    By default WebDyne will render blocks targeted by a render_block() call, even those that are outside the originating <perl>..</perl> section that made the call. Set to 0 to not render such blocks. Defaults to 1

$WEBDYNE_WARNINGS_FATAL
    If a programs issues a warning via warn() this constant determines if it will be treated as a fatal error. Default is 0 (warnings not fatal). Set to 1 if you want any warn() to behave as if die() had been called..

$WEBDYNE_CGI_DISABLE_UPLOADS
    Disable CGI.pm file uploads. Defaults to 1 (true - do not allow uploads).

$WEBDYNE_CGI_POST_MAX
    Maximum size of a POST request. Defaults to 512Kb

$WEBDYNE_ERROR_TEXT
    Display simplified errors in plain text rather than using HTML. Useful in interal WebDyne development only. By default this is 0 => the HTML error handler will be used.

$WEBDYNE_ERROR_SHOW
    Display the error message. Only applicable in the HTML error handler, as are all the following WEBDYNE_ERROR_SOURCE variables

$WEBDYNE_ERROR_SOURCE_CONTEXT_SHOW
    Display a fragment of the .psp source file around where the error occurred to give some context of where the error happened. Set to 0 to not display context.

$WEBDYNE_ERROR_SOURCE_CONTEXT_LINES_PRE
    Number of lines of the source file before the error occurred to display. Defaults to 4

$WEBDYNE_ERROR_SOURCE_CONTEXT_LINES_POST
    Number of lines of the source file after the error occurred to display. Defaults to 4

$WEBDYNE_ERROR_SOURCE_CONTEXT_LINE_FRAGMENT_MAX
    Max line length to show. Defaults to 80 characters.

$WEBDYNE_ERROR_BACKTRACE_SHOW
    Show a backtrace of modules through which the error propagated. On by default, set to 0 to disable,

$WEBDYNE_ERROR_BACKTRACE_SHORT
    Remove WebDyne internal modules from backtrace. Off by default, set to 1 to enable.

$WEBDYNE_AUTOLOAD_POLLUTE
    When a method is called from a <perl> routine the WebDyne AUTOLOAD method must search multiple modules for the method owner. Setting this flag to 1 will pollute the WebDyne name space with the method name so that AUTOLOAD is not called if that method is used again (for the duration of the Perl process, not just that call to the page). This is dangerous and can cause confusion if different modules use the same name. In very strictly controlled environments - and even then only in some cases - it can result is faster throughput. Off by default, set to 1 to enable.

SEE ALSO

http://webdyne.org/

COPYRIGHT AND LICENSE

WebDyne is Copyright © Andrew Speer 2005-2010. Webdyne is dual licensed. It is released as free software released under the Gnu Public License (GPL)[2], but is also available for commercial use under a proprietary license - please contact the author for further information.

WebDyne is written in Perl and uses modules from CPAN[3] (the Comprehensive Perl Archive Network). CPAN modules are Copyright © the owner/author, and are available in source from CPAN directly. All CPAN modules used are covered by the Perl Artistic License[4]

CREDITS

WebDyne relies heavily on modules and code developed and open-sourced by other authors. Without Perl, and Perl modules such as mod_perl/FCGI, CGI.pm, HTML::TreeBuilder and Storable, WebDyne would not be possible. To the authors of those modules - and all the other modules used to a lesser extent by WebDyne - I convey my thanks.

AUTHOR

Current maintainer: Andrew Speer, andrew.speer@webdyne.org

BUGS

Please report any bugs or feature requests to "bug-webdyne at rt.cpan.org", or via http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebDyne

NOTES

1.  http://webdyne.org
    http://webdyne.org/

2.  Gnu Public License (GPL)
    http://www.gnu.org/copyleft/gpl.html

3.  CPAN
    http://www.cpan.org

4.  Perl Artistic License
    http://www.perl.com/pub/a/language/misc/Artistic.html