Reference

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 subroutine/method nominated by the handler attribute. If this tag is invoked without a handler attribute, text between the tags will be interpreted as perl code and executed. If invoked with a handler attribute, text between the tags will be interpreted as a template - which can be output by a call to the WebDyne render() method within the handler.

<perl
  [handler=METHOD]
  [require=MODULE | FILE]
  [import=FUNCTION [, FUNCTION ...]]
  [param=SCALAR | HASHREF]
  [run]
  [file]
  [hidden]
  [chomp]
  [autonewline]
>

handler=METHOD

Call an external Perl method from a module, or a subroutine in the __PERL__ block at the end of the PSP file. If the handler is specified as "fully qualified" module call (e.g. Digest::MD5::md5_hex()) then a require will be made automatically to load the module (Digest::MD5 in this example)

#  Call method in the same file
#
<perl handler="hello">
__PERL__
sub hello {
...
}

#  Call method in another class
#
<perl handler="Digest::MD5::md5_hex()">

require=MODULE | FILE

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")

#  Load a module
#
<perl require="Digest::MD5">

#  Load a file
#
<perl require="module.pm">

import=FUNCTION [, FUNCTION …]

Import a single or multiple functions into the file namespace. Use a single SCALAR for importing one function, or pass an ARRAY reference for multiple functions.

# Import single function
#
<perl require="Digest::MD5" import="md5_hex">

# Import multiple functions
#
<perl require="Digest::MD5" import="@{'md5_hex', 'md5_base64'}">
<perl require="Digest::MD5" import="@{qw(md5_hex md5_base64)}">

Imported methods available anywhere in the namespace of that page.

param=SCALAR | HASHREF

Parameters to be supplied to perl routine, can be a single SCALAR value (string, numeric etc.) or a HASH reference.

#  Pass parameters to a handler. Single parameter
#
<perl handler="hello" param="Bob">

#  Pass hash ref
#
<perl handler="hello" param="%{ name=> 'Bob', age => 42 }">

static

Boolean flag. The Perl code to be run once only and the output cached for all subsequent requests. If omitted the code is not cached (i.e. it is run each time). If omitted the page is

run

Boolean flag. If evaluated to a true value exists the code is run, if not the code is skipped. If omitted the code is run by default. Useful for conditional running of code when a form has been submitted or a particular logic threshold reached.

#  Run code only at 4am
#
<perl handler="banner" run="(localtime)[2] == 4">

#  Run code only if a "name" form parameter supplied, all below equivalent
#
<perl handler="hello" run="+{name}"> ...
<perl handler="hello" run="!{! exists $_{'name'} !}"> ...
<perl handler="hello" run="!{! defined shift()->CGI->param('name') !}

file

Boolean flag. Force package|require attribute value 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

Boolean flag. The output from the Perl module will be hidden and no rendered to the page.

display=0

Equivalent to setting hidden attribute.

chomp

Boolean flag. Any new lines at the end of the output will be truncated.

autonewline

Boolean flag. A newline character will be inserted between each print statement.

<json>

Run Perl code similar to <perl> tag but expects code to return a HASH, ARRAY ref or plain scalar, which is encoded into JSON, outputting within 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. Takes the same options as the <perl> tag and behaves similarly - if a handler attribute is given it is called, if the perl attribute is given text between the <json> tags in treated as in-line perl code and executed.

<json
  [id=NAME]
  [handler=METHOD]
  [pretty]
  [canonical]
  [perl]
>

id=NAME

the DOM ID the <script> tag output from the tag will be given, e.g. <script id="mydata" type="application/json">{"foo":1}</script>

pretty

Boolean flag. Use the JSON pretty() method to format the output data into something more human readable. Not enabled by default. Enable with pretty=1 attribute or globally via $WEBDYNE_JSON_PRETTY=1 configuration setting.

canonical

Boolean flah. Use the JSON canonical() method to sort JSON data. Enabled by default, disable using canonical=0 attribute value or via $WEBDYNE_JSON_CANONICAL=0 configuration setting.

perl

Interpret content between starting and ending <json> tag as perl code and run it. The code should return a HASH, ARRAY or BOOLEAN value which will then be encoded to JSON data.

handler=METHOD

Call the perl method nominated. The code should return a HASH, ARRAY or BOOLEAN value which will then be encoded to JSON data.

Note

If returning JSON boolean values in code you should use the JSON::true and JSON::false values rather than 0 or 1, e.g.

<start_html>
<json handler/>
...
__PERL__
use JSON:
sub handler {
    return { enabled => JSON::true }
}

<block>

Block of HTML code to be optionally rendered if desired by call to render_block() Webdyne method:

<block
  name=NAME
  [display]
  [static]
>

name=NAME

Mandatory. The name for this block of PSP or HTML. Referenced when rendering a particular block within perl code, e.g. return $self->render_block("foo")

display

Boolean flag. Force display of this block even if not invoked by render_block() method in handler. Useful for prototyping or conditional display. Any true value will force display, so this can be coupled with a form parameter to only show a block when a form has been submitted in a similar form to the <perl> tag run attribute.

#  Only show a block if a name parameter has been supplied 
#
<block name="showname" display="+{name}">
Thank you for registering +{name} !
</block>

static

Boolean flag. This block is rendered once only and the output cached for all subsequent requests

<include>

Include HTML, PSP or text from an external file. Capable of just pulling in just the <head>,<body> or a <block> 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.

<include
  file=PATH
  [block=NAME]
  [wrap=TAG]
  [head]
  [body]
  [nocache]
>

file=PATH

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

head

Boolean flag. File is an HTML or PSP file and we want to include just the <head> section

body

Boolean flag/ File is an HTML or PSP file and we want to include just the <body> section.

block=NAME

File is a PSP file and we want to include a <block> section from that file with the nominated name.

wrap=TAG

Wrap the text from the included file in the nominated tag. Do not use <> symbols, just the plain tag name:

#  Include the protocols file and wrap in <pre>
#
<include="/etc/protocols" wrap="pre">

nocache

Don't cache the results of the include, bring them in off disk each time. Will incur performance penalty

<api>

Respond to a JSON request made from a client. Takes the same options as the <perl> tag and behaves similarly - if a handler attribute is given it is called, if the perl attribute is given text between the <api> tags in treated as in-line perl code and executed. Responses from perl code are encoded as JSON and returned.

<api
  pattern=ROUTE
  [destination=HASHREF | dest=HASHREF | data=HASHREF]
  [option=HASHREF]
>

pattern=ROUTE

Mandatory. Name of Router::Simple pattern we want to serve, e.g. /api/{user}/:id

destination=HASHREF

Hash we want to supply to perl routine if match made. See Route::Simple

option=HASHREF

Match options, GET, PUT etc. Router::Simple

<htmx>

Serve HTML fragments in response to htmx type requests (or similar clients). Takes the same options as the <perl> tag and behaves similarly - if a handler attribute is given it is called, if the perl attribute is given text between the <api> tags in treated as in-line perl code and executed.

<htmx
  [handler=METHOD]
  [perl]
  [display]
  [force]
>

display

Boolean. If evaluates to true then this <htmx> snippet fires. You can have multiple htmx tag sections in a page, but only one can fire at a time. Use this attribute in conjunction with dynamic evaluation

#  Fire htmx tag only if a name parameter matches
#
<htmx display="!{! $_{name} eq 'Bob' !}">
Hello Bob
</htmx>

#  Or Alice. Both tags can live in same document as only one will ever fire
#
<htmx display="!{! $_{name} eq 'Alice' !}">
Hello Alice
</htmx>

force

Boolean. Force the code referenced by a <htmx> tag to run, and content be returned/displayed even if the request is not triggered by the htmx javascript module (which is determined by looking for a hx-request HTTP header). Useful for troubleshooting/debugging and/or showing what the generated HTML snippet will look like. Can be dynamic and be triggered by GET parameter:

<htmx force="+{debug}">
This is my output
</htmx>

perl

Boolean. Interpret content between starting and ending <htmx> tags as perl code and run it. Anything returned by the perl code will be sent as the HTML fragment.

handler=METHOD

Call the perl method nominated. Whatever is returned or rendered by the handler will be returned as the HTML fragment.

<dump>

Display CGI and other parameters in Data::Dumper dump format. Useful for debugging. Only rendered if $WEBDYNE_DUMP_FLAG global set to 1 in WebDyne constants or the display|force attribute specified (see below). Useful while troubleshooting or debugging pages.

<dump
  [display]
  [force]
  [all]
  [cgi]
  [env]
  [constant]
  [version]
>

display|force

Boolean. Force display even if $WEBDYNE_DUMP_FLAG global not set

all

Boolean. Display all diagnostic blocks

cgi

Boolean. Display CGI parameters and query strings

env

Boolean. Display environment variables

constant

Boolean. Display Webdyne configurationconstants

version

Boolean. Display version strings

<start_html>

Start a HTML page with all conventional tags. This will produce the output:

<html><head><title></title><meta></head><body>

with appropriate content attributes as output.

<start_html
  [title=TEXT]
  [meta=HASHREF]
  [style=URL | ARRAYREF]
  [script=URL | ARRAYREF]
  [base=URL]
  [target=TARGET]
  [include=PATH | ARRAYREF]
  [include_script=PATH | ARRAYREF]
  [include_style=PATH | ARRAYREF]
  [static]
  [cache=METHOD]
>

title=TEXT

Content to be inserted into the <title> section tag.

meta=HASHREF

Meta section content, supplied as a hash reference. Processing is nuanced. Standard key=>value hash pairs are displayed as <meta name=key content=value> meta tags. Pairs of the type "property=name"=>value are displayed as <meta property=name content=value>.

<start_html meta="%{ author => 'Bob Smith', 'http-equiv=refresh' => '5; url=https://www.example.com' }">

Will produce:

<meta name="author" content="Bob Smith">
<meta http-equiv="refresh" content="5; url=https://www.example.com" >

style=URL | ARRAYREF

Stylesheets to load. Values to this attribute will be output as href attributes of type rel=stylesheet in a <link> tag.

<start_html style="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4">

Will produce:

<link href="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4" rel="stylesheet">

Array types are supported as values to the style property to allow multiple style sheet <link> tags to be created at once, e.g.

<start_html style="@{
    'https://cdn.jsdelivr.net/npm/water.css@2/out/water.css',
    'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css'
}">

Will produce:

<link href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css" rel="stylesheet">
<link href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css" rel="stylesheet">

script=URL | ARRAYREF

Similar facility to the style attribute. Any values supplied to this attribute will be output as src attributes to a <script> tag.

<start_html script="https://cdn.jsdelivr.net/npm/chart.js">

Will produce:

<script src="https://cdn.jsdelivr.net/npm/chart.js">

Anything supplied after the URL section as an anchor will be used in the script tag as an attribute, e.g.

<start_html script="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js#defer&integrity=sha..">

Will produce:

<script defer integrity=sha.. src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js">

As per the style attribute you can supply an array of resources to load using the same syntax.

base, target = URL, TARGET

Generate a <base> tag within the <head> section containing attributes equivalent to href=value of the base attribute, target=value of the target attribute

<start_html base="https://example.com" target="_blank">

Will produce:

<base href="https://example.com/" target="_blank">

include=PATH | ARRAYREF

Will include the raw text from the nominated file (supplied as the value) within the <head> section. No processing is done, the file contents are inserted verbatim.

include_script=PATH | ARRAYREF

As per above include attribute, raw text from the nominated file is inserted into the <head> section, however it is wrapped in a <script> tag.

include_style=PATH | ARRAYREF

As per standard include attribute raw text from the nominated file is inserted into the <head> section, however it is wrapped in a <style> tag.

static

Boolean. If the static attribute is present in the <start_html> tag the entire page is designated static. It will be compiled and generated once (at first load) and the resulting HTML will be cached and served on subsequent loads.

cache=METHOD

Use a cache handler to determine how often the page should be recompiled. See the Caching section. Sample:

<start_html cache="&cache">

<end_html>

End a HTML page. This will produce the </body></html> tags. It is not strictly necessary as the parser will automatically close dangling tags if it gets to the end of the file without seeing them, however is provided for completeness.

<popup_menu>

Provided a drop-down menu of options for user to select from.

<popup_menu
  name=NAME
  values=ARRAYREF | HASHREF
  [labels=HASHREF]
  [multiple]
  [disabled=VALUE | ARRAYREF]
  [selected|defaults|default=VALUE | ARRAYREF]
>

name=NAME

The name associated with this form component. This is the CGI parameter to be interrogated for value(s) once the form is submitted.

values=ARRAYREF | HASHREF

List of items to be presented in the drop down. If an array ref labels will be the same as values. If a hash ref the value will be the hash key, the label the hash label.

labels=HASHREF

If values is presented as an array ref, a hash ref of labels to be associated with each value can be supplied.

multiple

Boolean. If enabled allows multiple options to be selected. If not present (disabled) only one option can be selected.

disabled=VALUE | ARRAYREF

Single (string scalar) item or multiple (array ref) items which should be greyed out (not selectable) in menu options.

selected | defaults | default=VALUE | ARRAYREF

Single (string scalar) item or multiple (array ref) items which should be pre-selected in menu options.

<radio_group>

Provide a grouped list of radio buttons for a user to choose from. Only one radio button item can be selected.

<radio_group
  name=NAME
  values=ARRAYREF | HASHREF
  [labels=HASHREF]
  [disabled=VALUE | ARRAYREF]
  [checked|defaults|default=VALUE | ARRAYREF]
>

name=NAME

The name associated with this form component. This is the CGI parameter to be interrogated for value(s) once the form is submitted.

values=ARRAYREF | HASHREF

List of items to be presented. If an array reference, labels will be the same as values. If a hash refence the value will be the hash key, the label the hash value.

labels=HASHREF

If values is presented as an array ref a hash ref of labels to be associated with each value can be supplied.

disabled=VALUE | ARRAYREF

Single (string) or multiple (array ref) of items which should be greyed out (not selectable) in radio group items.

checked | defaults | default=VALUE | ARRAYREF

Single (string) or multiple (array ref) items which shoul be pre-selected in radio group items.

<checkbox_group>

Provide a grouped list of checkbox items for a user to choose form. Multiple checkboxes can be selected.

<checkbox_group
  name=NAME
  values=ARRAYREF | HASHREF
  [labels=HASHREF]
  [disabled=VALUE | ARRAYREF]
  [checked|defaults|default=VALUE | ARRAYREF]
>

name=NAME

The name associated with this form component. This is the $self->CGI() parameter to be interrogated for value(s) once the form is submitted.

values=ARRAYREF | HASHREF

List of items to be presented. If an array ref labels will be the same as values. If a hash ref the value will be the hash key, the label the hash label.

labels=HASHREF

If values is presented as an array ref a hash ref of labels to be associated with each value can be supplied.

disabled=VALUE | ARRAYREF

Single (string) or multiple (array ref) items which should be greyed out (not selectable) in checkbox group items.

checked|defaults|default=VALUE | ARRAYREF

Single (scalar) or multiple (array ref) items which should be pre-selected in checkbox group items.

<checkbox>

Single checkbox for a user to select or clear.

<checkbox
  name=NAME
  [value=VALUE | BOOLEAN]
  [disabled]
>

name=NAME

The name associated with this form component. This is the CGI parameter to be interrogated for value(s) once the form is submitted.

value=VALUE | BOOLEAN

The value to be returned in the CGI parameter if this checkbox is ticked (selected). If not supplied defaults to 1.

disabled

If present the checkbox will be displayed but cannot be selected.

Note

In order to retain state all checkbox form items will present a hidden parameter with the same name as the checkbox. This is notable because querying the parameter associated with a checkbox component will always return a Hash::MultiValue object with two items, the last of which is the checkbox value. When using $self->CGI->param(<checkbox name>) form of query, or $_{<checkbox name>} the user selected checkbox value will always be returned as a boolean or scalar value.

<scrolling_list>

Presents a scrolling list of options for a user to choose from. Attributes are identical to those of the <popup_menu> tag with the addition of a size attribute.

<scrolling_list
  name=NAME
  size=ROWS
  values=ARRAYREF | HASHREF
  [labels=HASHREF]
  [multiple]
  [disabled=VALUE | ARRAYREF]
  [selected|defaults|default=VALUE | ARRAYREF]
>

name=NAME

The name associated with this form component. This is the CGI parameter to be interrogated for value(s) once the form is submitted.

size=ROWS

Number of rows to make visible in user interface for the scrolling list.

The following attributes behave identically to <popup_menu>:

• values=ARRAYREF | HASHREF

• labels=HASHREF

• multiple

• disabled=VALUE | ARRAYREF

• selected|defaults|default=VALUE | ARRAYREF

<textarea>

A text box for freeform text entry. All attributes are the same as the HTML standard <textarea> tag with attributes:

<textarea
  name=NAME
  [default=TEXT]
  [force]
  (all standard HTML <textarea> attributes)
>

name=NAME

The name associated with this form component. This is the CGI parameter to be interrogated for value(s) once the form is submitted.

default=TEXT

The default content to be pre-filled out in the <textarea> component

force

By default the component is stateful, and user entered text will persist after form submission. Setting the force attribute will always present the default content regardless of user input.

<textfield>

The standard <input type="text"> tag type. User input with this tag is persistent. All standard <input> tag attributes are supported. The name and force attributes are supported as per other tags.

<password_field>

The standard <input type="password"> tag type. User input with this tag is persistent. The name and force attributes are supported as per other tags.

<filefield>

The standard <input type="file"> tag type. User input with this tag is persistent. When querying this parameter after form submission responses will be in the form of a Plack::Request::Upload object. User input with this tag is persistent. Example to demonstrate minimal file upload facility:

<start_html title="File Upload">
<start_multipart_form>
<filefield name="file" multiple required>
<p>
<submit name=Upload>
<end_form>

<pre>
<perl handler/>
</pre>

__PERL__

use Data::Dumper;
sub handler {

    my $self=shift();
    my $cgi_or=$self->CGI();
    return Dumper($cgi_or->uploads()->flatten);

}

<image_button>

The standard <input type="image"> tag type.

<button>

The standard <input type="button"> tag type.

<submit>

The standard <input type="submit"> tag type to initiate form submission.

<hidden>

The standard <input type="button"> tag type.

<start_form>

Start a form with method=POST and encoding type enctype="application/x-www-form-urlencoded" (implicit)

<start_multipart_form>

Start a form with method=POST and encoding type enctype="multipart/form-data"

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, e.g. $self->print("Hello World")). 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 a CGI::Simple type 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=>valufge, ..>).

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). Rendered blocks must be "published' if visibility required via return as array, or return of $self->render().

render_reset()

Erase anything previously set to render - it will not be sent to the browser. Limited use, may be helpful in error handling to "pull" anything previously published and replace with error message.

redirect( uri=>uri | file=>filename | html=>\html_text | json=>\json_text | text=>\plain_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. Content type header will be automatically adjusted to MIME type appropriate for type if redirecting to html, json or plain text content.

inode( <seed>, <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(s) combined with other information (such as $r->location) to generate a unique UUID. Seed only needs to be supplied if using cache handlers, see the "Caching" section

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( <output> ), printf( <output> ), say( <output> )

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 (unless autonewline() is set), where as say() does.

autonewline()

Get or set the autonewline flag. If set will add a new line automatically when using print() or $self->print(), essentially emulating say(). Supply undef or 0 to clear.

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.

err( <message> )

Return and/or raise an error to the WebDyne handler. Supply the actual error message as text.

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_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.

$WEBDYNE_ALPINE_VUE_ATTRIBUTE_HACK_ENABLE

The HTML parser use by WebDyne does not recognise the @ symbol as a valid attribute character, thus if using Alpine JS or Vue shortcuts in attributes such as <button @click="open = true"> the @click attribute won't be parsed corrected. The @click attribute is a shortcut to x-on, and thus the full attribute is <button x-on:click="open = true">. This config item defaults to converting the "@" symbol in attributes to "x-on:". If using Vue change to "v-on:"

$WEBDYNE_HTTP_HEADER_AJAX_HR

A HASH reference of HTTP header names used to determine if a request is interpreted as a htmx or Alpine Ajax type request, triggering only partial HTML return (either the body only of a normal PSP page, or a <htmx> tag fragment). Defaults to {qw(hx-request x-alpine-request)}.

$WEBDYNE_HTMX_FORCE

Under normal conditions a <htmx> tag isn't rendered unless the request contains a HTTP header name designating it as an AJAX type request from htmx or Alpine Ajax style libraries. Setting this config item will force rendering of a <htmx> tags even if the request doesn't contain a header designating it as a htmx style request. Equivalent to setting the force=1 attribute on all <htmx> tags. Defaults to 0 (do not render).

$WEBDYNE_PSGI_STATIC

Allow the webdyne.psgi Plack instance to serve static pages (non PSP pages) such as style sheets, javascript, images etc. Allowed static file extensions are designated by the $WEBDYNE_MIME_TYPE_HR config item - only files with extensions in that config item will be served. Defaults to 1 (allow static pages to be served)

$WEBDYNE_MIME_TYPE_HR

Hash reference of file extensions and MIME types which will be allowed to be served if $WEBDYNE_PSGI_STATIC is enabled. See source code of WebDyne/Constant.pm for defaults.

$WEBDYNE_HTTP_HEADER

Hash reference of default HTTP headers name and values to be sent in response to all WebDyne requests. See source code of WebDyne/Constant.pm for defaults.

Tip

Configuration items can be overridden by setting of environment variables of the same name with the desired value.

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

Environment Variables

All WebDyne configuration items can be overridden by setting an environment variable of the same same when starting the PSGI version, or via an Apache SetEnv directive, e.g:

#  Start webdyne plack instance with extended error display for this run.
#
$ WEBDYNE_ERROR_SHOW_EXTENDED=1 plackup `which webdyne.psgi`

In addition to the configuration overrides the following environment variables are available:

WEBDYNE_CONF

Location of the WebDyne configuration file to load. Loading of an alternate configuration file will bypass loading of any/all other configuration files (e.g. /etc/webdyne.conf.pl). They are not additive - only configuration directives in the nominated by this environment variable will be processed. e.g.

#  Start webdyne with an alternate config file
#
WEBDYNE_CONF=./myconf.pl webdyne.psgi

Caution

Your config file must be valid Perl syntax and in the format expected. Always check it with perl -c -w myconf.pl to ensure it is correct.

DOCUMENT_ROOT

Plack and Starman instances only - the starting home directory or file name (if file rather than directory) for the PSGI server to use. Defaults to the current working directory if none specified.

DOCUMENT_DEFAULT

Plack and Starman instances only - the default files to look for in a directory if none given via browser URL. Defaults to "app.psp".

WEBDYNE_DEBUG

When debugging enabled in modules only (see Troubleshooting). Set to 1 to enable all debugging (extremely verbose), or set to module/subroutine name to filter down to that area. e.g.

#  Debug the internal perl routine in WebDyne
#
$ WEBDYNE_DEBUG=perl perl -Ilib bin/wdrender time.psp
[23:28:24.699358 WebDyne (perl)] WebDyne=HASH(0x561d4a271a28) rendering perl tag in block ARRAY(0x561d4aaace20), attr $VAR1 = {
  'inline' => 1,
  'perl' => ' localtime() '
};

[23:28:24.699490 WebDyne (perl)] found inline perl code $VAR1 = \' localtime() ';
, param $VAR2 = undef;

<!DOCTYPE html><html lang="en"><head><title>Untitled Document</title><meta charset="UTF-8"><meta content="width=device-width, initial-scale=1.0" name="viewport"><link href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.classless.min.css" rel="stylesheet"><link href="/style.css" rel="stylesheet"></head>
<body><h1>Example File</h1><p> The current server time is: Sun Jan 11 23:28:24 2026</p></body></html>

WEBDYNE_DEBUG_FILTER

When debugging enabled only output debug information that matches the regex given by this environment variable. Useful to further filter down to areas of interest.

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>