Skip to content

Additional Notes

Things to note or information not otherwise contained elsewhere:

About handler and method calling attributes in tags

Some WebDyne attributes name a Perl subroutine to call. In PSP syntax an attribute with no explicit value is treated as having the attribute name as its value, so <perl handler> is a shortcut for <perl handler="handler">. Defining a handler subroutine in the __PERL__ section is therefore the shortest way to make a simple PSP file call server-side Perl code:

<start_html>
<perl handler/>

__PERL__

sub handler {
    my $self=shift();
    return "Hello from a handler";
}

For clarity, or where a page has more than one callable routine, the longer form can be used instead. For example <perl handler="my_handler"> calls my_handler and behaves the same way; it just takes more typing:

<start_html>
<perl handler="my_handler"/>

__PERL__

sub my_handler {
    my $self=shift();
    return "Hello from my_handler";
}

The same bare-attribute convention applies to other handler-style attributes in the context where those attributes are valid. In <perl>, <api> and <htmx>, handler names the Perl routine to call. In <start_html>, sse and ws name the PAGI Server-Sent Events and WebSocket handlers, so <start_html sse> means <start_html sse="sse">, and <start_html ws> means <start_html ws="ws">. The cache attribute on <start_html> similarly names the cache handler used by the caching layer. The method attribute is accepted as a compatibility synonym for handler on <perl>-style calls, but handler is preferred in new examples.

About <start_html> shortcuts

The <start_html> tag exists as a convenience for common page setup. It expands to normal HTML, including the document type, opening <html> and <body> tags, and a generated <head> section. It is not a separate client-side technology; the browser receives ordinary HTML output.

Some <start_html> attributes are small formatting shortcuts intended for quick page construction. For example h1 through h6 insert a heading based on the page title, and hr adds a horizontal rule after that generated heading. These are useful for quick examples, diagnostics and small tools, but they can always be replaced with explicit HTML in the body of the page.

Other <start_html> shortcuts load common frontend libraries or stylesheets. The built-in shortcuts include pico for Pico CSS, htmx for htmx, and alpine for Alpine.js. They exist to keep small PSP examples readable and to avoid repeating common CDN <link> or <script> tags. For example <start_html alpine> loads the configured Alpine.js script. Longer form HTML is still supported, so you can load JavaScript or CSS in the traditional way with explicit <script> and <link> tags, or by using the script and style attributes documented in the <start_html> tag reference.

How to check syntax of a PSP file

To check the syntax of a PSP file - or more specifically any Perl code in the __PERL__ section - you can use the wdlint command. Take this file with an assignment syntax error in the server_time() routine:

<start_html>
Hello World <? server_time() ?>
__PERL__
#!perl

sub server_time {
    my 2==1; #Error here
}

Run the commandwdlint <filename.psp> to check for syntax error and report back:

$ wdlint check.psp
syntax error at check.psp line 8, near "my 2"
check.psp had compilation errors.

How to pass $self ref if using processing instructions

If you use the processing instruction form of calling a perl method it will not pass the WebDyne object ref through to your code. You can pass it by supplying @_ as a parameter, or just shift() and your own parameters:

<start_html>
Hello World <? server_time(@_) ?>
Hello World <? server_time(shift(), 'UTC' ?>
Hello World <perl handler="server_time" param="UTC"/>
__PERL__

sub server_time {
    #  Now we can get self ref
    my ($self, $timezone)=@_;

    #  Do something and return
    $self->do_something()
}

Use of hash characters for comments in PSP files

Any # characters at the very start of a PSP file (before a <html> or <start_html>) tag are treated as comments and discarded - they will not be stored or displayed (they are not translated into HTML comments). This allows easy to read comments at the start of PSP files. Any # characters after the first valid tag are not treated specially - they will be rendered as normal HTML:

#  This is my server time display file
#
#  VERSION=1.23
#
<start_html>
Server local time is: <? localtime ?>

The <checkbox> tag will always set a hidden form field

The <checkbox> tag is unusual in that it adds a hidden field (with the same name as the checkbox) to the HTML page to retain state. Thus if you are examining the checkbox parameter from CGI via $_{'checkbox_name'} or $self->CGI->param('checkbox_name') you may get an array rather than a single value. The value of the checkbox (boolean, checked or unchecked, i.e. 1 or 0) will always be the first value returned. So the code if ($_{'checkbox_name'}) { .. do_something } will work as expected - but just be careful if using in an array context.

About this documentation

This documentation is written with the XMLMind XML Editor, then converted to Markdown with pandoc and displayed using MKdocs. The documentation for WebDyne is maintained on a Github repository.