Reference¶

Tag Reference¶

Reference of WebDyne tags and supported attributes

Core Tags¶

<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]
  [static]
  [file]
  [hidden]
  [display=0]
  [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 a file path 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 is 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).
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 not rendered to the page.
display=0: Equivalent to setting hidden attribute.
method=METHOD: Compatibility alias for handler. Prefer handler in new documentation and examples.
package=PACKAGE: Optional package component used when constructing a fully qualified handler call. Prefer a fully qualified handler value unless separating the package and method names is useful for compatibility with older PSP files.
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 flag. 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. Can pull in just the <head>, <body> or a <block> section from another HTML or PSP file. If pulled in from a PSP file it will be compiled and interpreted in the context of the current page.

<include
  file=PATH | ARRAYREF
  [block=NAME]
  [wrap=TAG]
  [head]
  [body]
  [param=HASHREF]
  [nocache]
>

file=PATH | ARRAYREF: Mandatory. Name of file or files 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 a plain file include in the nominated tag. Do not use <> symbols, just the plain tag name. This option applies when including a file directly, not when extracting head, body, or block content from another HTML or PSP file.

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

param=HASHREF: Parameter hash supplied while rendering included PSP content. This is used when extracting a head, body, or named block from another PSP file.
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 the text between the <api> tags is treated as in-line perl code and executed. Responses from perl code are encoded as JSON and returned.

<api
  pattern=ROUTE
  [match=ROUTE]
  [destination=HASHREF | dest=HASHREF | data=HASHREF]
  [option=HASHREF | options=HASHREF | constraint=HASHREF | constraints=HASHREF]
  [canonical]
>

pattern=ROUTE: Mandatory. Name of Router::Simple pattern we want to serve, e.g. /api/{user}/:id. The match attribute is accepted as an alias.
destination=HASHREF | dest=HASHREF | data=HASHREF: Hash we want to supply to perl routine if match made. See Router::Simple
option=HASHREF | options=HASHREF | constraint=HASHREF | constraints=HASHREF: Match options, GET, PUT etc. Router::Simple
canonical: Boolean flag. Use the JSON canonical() method to sort JSON response data. Enabled by default, disable using canonical=0 attribute value or via $WEBDYNE_JSON_CANONICAL=0 configuration setting.

<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 the text between the <htmx> tags is 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]
  [lib | inc]
  [constant]
  [dir_config]
  [version]
>

display|force: Boolean. Force display even if $WEBDYNE_DUMP_FLAG global not set
all: Boolean. Display all diagnostic blocks
cgi: CGI parameters and query strings are always displayed once dump output is enabled.
env: Boolean. Display environment variables
lib | inc: Boolean. Display the Perl include paths and loaded module table (@INC and %INC).
constant: Boolean. Display WebDyne configuration constants.
dir_config: Boolean. Display WebDyne request directory configuration.
version: Version strings are always displayed once dump output is enabled.

<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]
  [style_prepend=URL | ARRAYREF]
  [style_append=URL | ARRAYREF]
  [script=URL | ARRAYREF]
  [script_prepend=URL | ARRAYREF]
  [script_append=URL | ARRAYREF]
  [base=URL]
  [target=TARGET]
  [author=EMAIL]
  [include=PATH | ARRAYREF]
  [include_script=PATH | ARRAYREF]
  [include_style=PATH | ARRAYREF]
  [static]
  [cache=METHOD]
  [handler=METHOD]
  [h1 | h2 | h3 | h4 | h5 | h6]
  [hr]
  [sse=METHOD]
  [ws=METHOD]
  [pico]
  [htmx]
  [alpine]
>

Any attributes not listed here are passed through to the generated <html> tag after WebDyne has consumed the page-control attributes. The shortcut attributes pico, htmx, and alpine are defined by WEBDYNE_START_HTML_SHORTCUT_HR and can be changed or extended in WebDyne configuration.

Values in WEBDYNE_START_HTML_PARAM are applied before attributes from the page <start_html> tag. If a page supplies the same attribute with a value, the page value replaces the configured value for that attribute. For example, style replaces a configured style list, and script replaces a configured script list. Use style_prepend, style_append, script_prepend, or script_append when a page should add resources around configured defaults instead of replacing them.

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

Linked stylesheets are emitted before include_style content.

style_prepend=URL | ARRAYREF; style_append=URL | ARRAYREF: Stylesheets to add before or after the current style value. This is useful when WEBDYNE_START_HTML_PARAM supplies default styles and a page needs to add styles without replacing those defaults.

<start_html style_append="app.css">

The existing style attribute keeps its current override behaviour. If style is supplied with style_prepend or style_append, the prepend and append values are added around the explicit style value.

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.

External scripts are emitted before include_script content.

script_prepend=URL | ARRAYREF; script_append=URL | ARRAYREF: Scripts to add before or after the current script value. This is useful when WEBDYNE_START_HTML_PARAM supplies default scripts and a page needs to add scripts without replacing those defaults.

<start_html script_append="app.js">

The existing script attribute keeps its current override behaviour. If script is supplied with script_prepend or script_append, the prepend and append values are added around the explicit script value.

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

author=EMAIL: Generate an author link in the <head> section. The supplied value is URL encoded and emitted as a <link rel="author" href="mailto:..."> tag.
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. Included scripts are emitted after external scripts from the script attribute.
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. Included styles are emitted after linked stylesheets from the style attribute.
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">

handler=METHOD: Store a page handler method in the compiled page metadata. This is used by WebDyne's request dispatch path when a page needs to nominate a handler from the <start_html> tag instead of relying on surrounding server configuration.
h1 | h2 | h3 | h4 | h5 | h6: Boolean heading shortcut. If one of these attributes is present and a title is available, WebDyne inserts a heading of the requested level at the start of the generated <body> using the page title text.

<start_html title="Hello World" h1>

hr: Boolean heading companion shortcut. When used with one of h1 through h6, WebDyne inserts an <hr> immediately after the generated heading.

<start_html title="Hello World" h1 hr>

sse=METHOD: Mark the page as providing Server-Sent Events when run through the PAGI request layer. The value is stored in WebDyne page metadata and names the async subroutine to call for SSE requests. If used as a bare boolean attribute, the method name defaults to sse.

<start_html sse>

ws=METHOD: Mark the page as providing WebSocket handling when run through the PAGI request layer. The value is stored in WebDyne page metadata and names the async subroutine to call for WebSocket requests. If used as a bare boolean attribute, the method name defaults to ws.

<start_html ws>

pico: Framework shortcut defined by WEBDYNE_START_HTML_SHORTCUT_HR. Adds Pico CSS to the style list, using https://cdn.jsdelivr.net/npm/@picocss/pico@latest/css/pico.min.css by default.

<start_html pico title="Pico Example">

htmx: Framework shortcut defined by WEBDYNE_START_HTML_SHORTCUT_HR. Adds htmx to the script list, using https://cdn.jsdelivr.net/npm/htmx.org@latest/dist/htmx.min.js by default.

<start_html htmx>

alpine: Framework shortcut defined by WEBDYNE_START_HTML_SHORTCUT_HR. Adds Alpine.js to the script list, using https://cdn.jsdelivr.net/npm/alpinejs@latest/dist/cdn.min.js#defer by default. The URL fragment is interpreted as script attributes, so the generated <script> tag includes defer.

<start_html alpine>

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

Form Tags¶

<popup_menu>¶

Provide a drop-down menu of options for a user to select from. Other standard HTML <select> attributes are passed through to the generated element.

<popup_menu
  name=NAME
  values=ARRAYREF | HASHREF
  [labels=HASHREF]
  [attributes=HASHREF]
  [label=TEXT]
  [multiple]
  [disabled=VALUE | ARRAYREF]
  [selected | defaults | default=VALUE | ARRAYREF]
  [force]
  (standard HTML <select> 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.
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. If predictable display order matters, use an array ref for values and a separate labels hash ref.
labels=HASHREF: If values is presented as an array ref, a hash ref of labels to be associated with each value can be supplied.
attributes=HASHREF: Hash reference of additional attributes to apply to individual <option> elements, keyed by option value.
label=TEXT: Wrap the generated <select> element in a <label> element using the supplied text.
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.
force: By default selected values are stateful, and submitted values for this field override the configured default or selected values. Setting force always uses the configured default or selected values.

<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]
  [attributes=HASHREF]
  [disabled=VALUE | ARRAYREF]
  [checked | defaults | default=VALUE | ARRAYREF]
  [linebreak]
  [force]
>

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 reference the value will be the hash key, the label the hash value. If predictable display order matters, use an array reference for values and a separate labels hash reference.
labels=HASHREF: If values is presented as an array ref a hash ref of labels to be associated with each value can be supplied.
attributes=HASHREF: Hash reference of additional attributes to apply to individual <input type="radio"> elements, keyed by radio value.
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 should be pre-selected in radio group items. Radio groups can only select one value; if multiple defaults are supplied, the first value in sorted order is used.
linebreak: Separate generated radio items with <br> tags.
force: By default checked values are stateful, and submitted values for this field override the configured defaults. Setting force always uses the configured defaults.

<checkbox_group>¶

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

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

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. If predictable display order matters, use an array ref for values and a separate labels hash ref.
labels=HASHREF: If values is presented as an array ref a hash ref of labels to be associated with each value can be supplied.
attributes=HASHREF: Hash reference of additional attributes to apply to individual <input type="checkbox"> elements, keyed by checkbox value.
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.
linebreak: Separate generated checkbox items with <br> tags.
force: By default checked values are stateful, and submitted values for this field override the configured defaults. Setting force always uses the configured defaults.

<checkbox>¶

Single checkbox for a user to select or clear.

<checkbox
  name=NAME
  [value=VALUE | BOOLEAN]
  [checked]
  [disabled]
  [label=TEXT]
  (standard HTML <input> 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.
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.
checked: If present the checkbox is initially selected. For the default boolean value path, submitted values for the field are stateful and override this initial setting.
label=TEXT: Wrap the generated checkbox in a <label> element using the supplied text.

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. This automatic hidden-field and persistence behaviour applies when no explicit value is supplied.

<scrolling_list>¶

Presents a scrolling list of options for a user to choose from. It uses the same attributes as <popup_menu> with the addition of a size attribute.

<scrolling_list
  (same attributes as <popup_menu>)
  [size=ROWS]
>

size=ROWS: Number of rows to make visible in the user interface for the scrolling list. If omitted, WebDyne sets this to the number of configured values.

<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]
  [label=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
label=TEXT: Wrap the generated <textarea> element in a <label> element using the supplied text.
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. Other standard HTML <input> attributes are passed through to the generated element.

<textfield
  name=NAME
  [value=TEXT]
  [label=TEXT]
  [force]
  (standard HTML <input> attributes)
>

label=TEXT: Wrap the generated input in a <label> element using the supplied text.
force: By default the field is stateful, and submitted values override the configured value. Setting force always uses the configured value.

<password_field>¶

The standard <input type="password"> tag type. It uses the same attributes as <textfield>, with the generated input type set to password.

<filefield>¶

The standard <input type="file"> tag type. It uses the same attributes as <textfield>, with the generated input type set to file. When querying this parameter after form submission responses will be in the form of a Plack::Request::Upload object. 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. It accepts standard HTML <input> attributes and supports label wrapping using the same behaviour as <textfield>.

<button>¶

The standard HTML <button> element. Standard button attributes and enclosed content are passed through to the generated element.

<submit>¶

The standard <input type="submit"> tag type to initiate form submission. It accepts standard HTML <input> attributes and supports label wrapping using the same behaviour as <textfield>.

<reset>¶

The standard <input type="reset"> tag type to reset form fields to their initial values. It accepts standard HTML <input> attributes and supports label wrapping using the same behaviour as <textfield>.

<defaults>¶

A CGI-style shortcut rendered as a submit input. It is supported for compatibility with CGI.pm-style form helpers and uses the same attributes as <submit>.

<hidden>¶

The standard <input type="hidden"> tag type. Standard HTML <input> attributes are passed through to the generated element.

<isindex>¶

Legacy <isindex> output is supported for compatibility, but the HTML element is deprecated and should not be used for new pages. Prefer normal form tags such as <start_form>, <textfield>, and <submit>.

<start_form>¶

Start a form with method=POST. Other standard HTML <form> attributes are passed through to the generated element.

<start_form
  [method=METHOD]
  (standard HTML <form> attributes)
>

<start_multipart_form>¶

Start a form with method=POST and enctype="multipart/form-data". Other standard HTML <form> attributes are passed through to the generated element. The enctype attribute can be overridden because form attributes are passed through, but this is normally only useful if you are deliberately replacing multipart form encoding.

<start_multipart_form
  [method=METHOD]
  [enctype=ENCODING]
  (standard HTML <form> attributes)
>

Method 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, 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 the current WebDyne request adapter. WebDyne provides a common request interface across Apache, PSGI, PAGI and command-line render contexts, with backend-specific details available where supported.
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.

Configuration Reference¶

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.

PSGI and PAGI root configuration¶

When the webdyne.psgi or webdyne.pagi wrapper builds an application it also loads $DOCUMENT_ROOT/.webdyne.conf.pl, if present. This applies both when the wrapper is started directly and when it is loaded by an external PSGI or PAGI server. If the effective document root is a file, the parent directory is checked for .webdyne.conf.pl.

This root configuration file is separate from request-directory configuration. When WEBDYNE_DIR_CONFIG_CWD_LOAD is enabled, WebDyne can also inspect a .webdyne.conf.pl file in the directory of the current PSP file, but only the WEBDYNE_DIR_CONFIG section is used from that per-directory file.

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 authoritative reference for constants defined by WebDyne::Constant is maintained with the module sidecar documentation and copied into the MkDocs module reference during documentation generation.

See WebDyne::Constant module reference for the complete list of constants, defaults, and behaviour descriptions.

Tip

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

Extension modules, for example WebDyne::Session, may define their own constants in their own WebDyne::*::Constant packages. See the relevant module reference pages for details.

Environment Variable Reference¶

All WebDyne configuration items can be overridden by setting an environment variable of the same name when starting PSGI or PAGI instances, 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¶

The starting home directory or file name (if file rather than directory) for PSGI and PAGI server wrappers to use. Defaults to the current working directory if none specified.

DOCUMENT_DEFAULT¶

The default file to look for in a directory if none is given via browser URL. The PSGI and PAGI constant layer defaults this to app.psp. The direct webdyne.psgi and webdyne.pagi command wrappers enable WebDyne's built-in index page by default unless DOCUMENT_DEFAULT, --index=FILE, or --no-index changes that behavior.

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.

Docker Runtime Server Tuning¶

The published WebDyne Docker images expose server tuning options through environment variables understood by the default container entrypoint.

Runtime server tuning options can also be supplied through environment variables. If these variables are not set, the underlying server defaults are used.

WEBDYNE_SERVER_PSGI_WORKERS: Sets the starman --workers option.
WEBDYNE_SERVER_PSGI_MAX_REQUESTS: Sets the starman --max-requests option.
WEBDYNE_SERVER_PSGI_BACKLOG: Sets the starman --backlog option.
WEBDYNE_SERVER_PSGI_KEEPALIVE_TIMEOUT: Sets the starman --keepalive-timeout option.
WEBDYNE_SERVER_PSGI_READ_TIMEOUT: Sets the starman --read-timeout option.
WEBDYNE_SERVER_PAGI_WORKERS: Sets the pagi-server --workers option.
WEBDYNE_SERVER_PAGI_MAX_REQUESTS: Sets the pagi-server --max-requests option.
WEBDYNE_SERVER_PAGI_LISTENER_BACKLOG: Sets the pagi-server --listener-backlog option.
WEBDYNE_SERVER_PAGI_TIMEOUT: Sets the pagi-server --timeout option.
WEBDYNE_SERVER_PAGI_REQUEST_TIMEOUT: Sets the pagi-server --request-timeout option.
WEBDYNE_SERVER_PAGI_MAX_CONNECTIONS: Sets the pagi-server --max-connections option.
WEBDYNE_SERVER_PAGI_MAX_BODY_SIZE: Sets the pagi-server --max-body-size option.

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>

File Locations¶

/etc/webdyne.conf.pl, ~/.webdyne.conf.pl, $DOCUMENT_ROOT/.webdyne.conf.pl: Used for storage of local constants that override WebDyne defaults. See the WebDyne::Constant section for details