WebDyne API¶

WebDyne tags¶

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|handler=method: Call an external Perl subroutine in from a module, or a subroutine in a __PERL__ block at the of the .psp file. If the handler is specified a module call (e.g. Digest::MD5::md5_hex()) then a require call will be load the module (Digest::MD5 in this example.
package|require=[Module::Name] | [Path/Filename.pm]: Load a Perl module or file needed to support a method call. E.g. <perl require=Digest::MD5/> to load the Digest::MD5 module. Anything with a [./\] character is treated as file patch to a Perl file (e.g. "/home/user/module.pm"), otherwise it is treated as module name ("Digest::MD5")
import=[function], <function>, <function> ..: Import a single or multiple functions into the file namespace. Use "import=name" for a single function, or pass an array ref (import="@{name1, name2}" for multiple functions. E.g. <perl require="Digest::SHA" import="@{qw(sha1 sha1_hex)}"/>. Functions are then available anywhere in the file namespace.
param=scalar|array|hash: Parameters to be supplied to perl routine. Supply array and hash using "@{1,2}" and "%{a=>1, b=>2}" conventions respectively, e.g. <perl method="sum2num" param="@{2,2}"/>
static=1: This Perl code to be run once only and the output cached for all subsequent requests.
file=1: Force package|require attribute to be treated as a file, even if it appears to "look like" a module name to the loader. Rarely needed, use case would be a Perl module in the current directory without an extension.
hidden=1: The output from the Perl module will be hidden.

<json>

Run Perl code similar to <perl> tag but expect code to return a HASH, ARRAY or SCALAR ref and encode into JSON, outputting in a <script> tag with type="application/json". When supplied with an id attribute this data can be used by any Javascript function in the page. All attributes are the same as the <perl> tag with the following extra attribute

id=[name]: ID this <script> tag will be given, e.g. <script id="mydata" type="application/json">[{"foo":1}]</script>

<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. Referenced when rendering a particular block in perl code, e.g. return $self->render_block("foo");
display=1: Force display of this block even if not invoked by render_block WebDyne method. Useful for prototyping.
static=1: This block rendered once only and the output cached for all subsequent requests

<include>

Include HTML or text from an external file. This includes pulling in the <head> or <body> section from another HTML or .psp file. If pulled in from a .psp file it will compiled and interpreted in the context of the current page.

file=filename: Mandatory. Name of file we want to include. Can be relative to current directory or absolute path.
head=1: File is an HTML or .psp file and we want to include just the <head> section
body=1: File is an HTML or .psp file and we want to include just the <body> section.
block=blockname: File is a .psp file and we want to include a <block> section from that file.
nocache: Don't cache the results of the include, bring them in off disk each time. Will incur performance penalty

<dump>

Display CGI parameters in dump format via CGI::Simple->Dump call. Useful for debugging. Only rendered if $WEBDYNE_DUMP_FLAG global set to 1 in WebDyne constants of the display|force attribute specified (see below). Useful while troubleshooting or debugging pages.

display|force=1: Optional. Force display even if $WEBDYNE_DUMP_FLAG global not set
all: Display all diagnostic blocks
cgi: Display CGI parameters and query strings
env: Display environment variables
constant: Display Webdyne constants
version: Display version strings

WebDyne methods¶

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::Simple object for the current request.
r(), request(): Returns an instance of the Apache request object, or a mock object with similar functionality when running under PSGI or FCGI
html_tiny(): Returns an instance of the HTML::Tiny object, can be used for creating programmatic HTML output
include(): Returns HTML derived from a file, using the same parameters as the <include> tag
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).
render_reset(): Erase anything previously set to render - it will not be sent to the browser.
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. If supplying HTML text to be rendered supply as a SCALAR reference.
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).
source_mtime(): Returns the mtime (modification time) of the source .psp file currently being rendered.
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.
filename(): Return the full filename (including path) of the file being rendered. Will only return the core (main) filename - any included files, templates etc. are not reported.
cwd(): Return the current working directory WebDyne is operating in.
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)
print(), printf(), say(): Render the output of the print(), printf() or say() routines into the current HTML stream. The print() and printf() methods emulate their Perl functions in not appending a new line into the output, where as say() does.
render_time(): Return the elapsed time since the WebDyne hander started rendering this page. Obviously only meaningful if called at the end of a page, just before final output to browser.

WebDyne Constants¶

Constants defined in the WebDyne::Constant package control various aspects of how WebDyne behaves. Constants can be modified globally by altering a global configuration file (/etc/webdyne.conf.pl under Linux distros), setting environment variable or by altering configuration parameters within the Apache web server config.

Global constants file¶

WebDyne will look for a system constants file under /etc/webdyne.conf.pl and set package variables according to values found in that file. The file is in Perl Data::Dumper format, and takes the format:

# sample /etc/webdyne.conf.pl file
#
$VAR1={
        WebDyne::Constant => {

                WEBDYNE_CACHE_DN       => '/data1/webdyne/cache',
                WEBDYNE_STORE_COMMENTS => 1,
                #  ... more variables for WebDyne package

       },

       WebDyne::Session::Constant => {

                WEBDYNE_SESSION_ID_COOKIE_NAME => 'session_cookie',
                #  ... more variables for WebDyne::Session package

       },

};

The file is not present by default and should be created if you wish to change any of the WebDyne constants from their default values.

Important

Always check the syntax of the /etc/webdyne.conf.pl file after editing by running perl -c -w /etc/webdyne.conf.pl to check that the file is readable by Perl. Files with syntax errors will fail silently and the variables will revert to module defaults.

Setting WebDyne constants in Apache¶

WebDyne constants can be set in an Apache httpd.conf file using the PerlSetVar directive:

PerlHandler     WebDyne
PerlSetVar      WEBDYNE_CACHE_DN                '/data1/webdyne/cache'
PerlSetVar      WEBDYNE_STORE_COMMENTS          1

#  From WebDyne::Session package
#
PerlSetVar      WEBDYNE_SESSION_ID_COOKIE_NAME  'session_cookie'

Important

WebDyne constants cannot be set on a per-location or per-directory basis - they are read from the top level of the config file and set globally.

Some 1.x versions of mod_perl do not read PerlSetVar variables correctly. If you encounter this problem use a <Perl>..</Perl> section in the httpd.conf file, e.g.:

# Mod_perl 1.x

PerlHandler     WebDyne
<Perl>
$WebDyne::Constant::WEBDYNE_CACHE_DN='/data1/webdyne/cache';
$WebDyne::Constant::WEBDYNE_STORE_COMMENTS=1;
$WebDyne::Session::Constant::WEBDYNE_SESSION_ID_COOKIE_NAME='session_cookie';
</Perl>

Where you need to set variables without simple string content you can use a <Perl>..</Perl> section in the httpd.conf file, e.g.:

# Setting more complex variables

PerlHandler     WebDyne
<Perl>
$WebDyne::Constant::WEBDYNE_CACHE_DN='/data1/webdyne/cache';
$WebDyne::Constant::WEBDYNE_STORE_COMMENTS=1;
$WebDyne::Session::Constant::WEBDYNE_SESSION_ID_COOKIE_NAME='session_cookie';
</Perl>

Warning

The letsencrypt certbot utility will error out when trying to update any Apache config file with <Perl> sections. To avoid this you put the variables in a separate file and include them, e.g. in the apache.conf file:

# Some config setting defaults. See documentation for full range. 
# Commented out # options represent defaults 
#
PerlRequire conf.d/webdyne_constant.pl

And then in the webdyne_constant.pl file:

use WebDyne;
use WebDyne::Constant;

#  Error display/extended display on/off. More granular options below. 
#  Set to 1 to enable, 0 to disable
#
$WebDyne::WEBDYNE_ERROR_SHOW=1;
$WebDyne::WEBDYNE_ERROR_SHOW_EXTENDED=1;

#  Extended error control.
#
#  $WebDyne::WEBDYNE_ERROR_SOURCE_CONTEXT_SHOW=1;
#  $WebDyne::WEBDYNE_ERROR_SOURCE_CONTEXT_LINES_PRE=4;
#  $WebDyne::WEBDYNE_ERROR_SOURCE_CONTEXT_LINES_POST=4;

Constants Reference¶

The following constants can be altered to change the behaviour of the WebDyne package. All these constants reside in the WebDyne::Constant package namespace.

$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: 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. Evaluating code in a Safe container is experimental and not supported or recommended for general WebDyne use.
$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 and considered experimental.
$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>
$WEBDYNE_HTML_PARAM: attributes for the <html> tag, default is { lang =>'en' }
$WEBDYNE_HEAD_INSERT: Any HTML you want inserted before the closing </head> tag, e.g. stylesheet or script includes to be added to every .psp page. Must be valid HTML <head> directives, not interpreted or compiled by WebDyne, incorporated as-is
$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::Simple file uploads. Defaults to 1 (true - do not allow uploads).
$WEBDYNE_CGI_POST_MAX: Maximum size of a POST request. Defaults to 512Kb
$WEBDYNE_JSON_CANONICAL: Set is JSON encoding should be canonical, i.e. respect the order of supplied data (slightly slows down encoding). Defaults to 1 (true - preserve variable order)
$WEBDYNE_ERROR_TEXT: Display simplified errors in plain text rather than using HTML. Useful in internal 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
$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.

Extension modules (e.g., WebDyne::Session) have their own constants - see each package for details.

WebDyne Directives¶

A limited number of directives are are available which change the way WebDyne processes pages. Directives are set in either the Apache .conf files and can be set differently per location. At this stage only one directive applies to the core WebDyne module:

WebDyneHandler: The name of the handler that WebDyne should invoke instead of handling the page internally. The only other handler available today is WebDyne::Chain.

This directive exists primarily to allow PSGI to invoke WebDyne::Chain as the primary handler. It can be used in Apache httpd.conf files, but is not very efficient:

#  This will work, but is not very efficient
#
<location /shop/>
PerlHandler     WebDyne
PerlSetVar      WebDyneHandler               'WebDyne::Chain'
PerlSetVar      WebDyneChain                 'WebDyne::Session'
</location>


#  This is the same, and is more efficient
#
<location /shop/>
PerlHandler     WebDyne::Chain
PerlSetVar      WebDyneChain                 'WebDyne::Session'
</location>