Skip to content

Extending WebDyne

WebDyne can be extended by the installation and use of supplementary Perl packages. There are several standard packages that come with the Webdyne distribution, or you can build your own using one of the standard packages as a template.

The following gives an overview of the standard packages included in the distribution, or downloadable as extensions from CPAN.

WebDyne::Chain

WebDyne::Chain is a module that will cascade a WebDyne request through one or more modules before delivery to the WebDyne engine. Most modules that extend WebDyne rely on WebDyne::Chain to get themselves inserted into the request lifecycle.

Whilst WebDyne::Chain does not modify content itself, it allows any of the modules below to intercept the request as if they had been loaded by the target page directly (i.e., loaded in the __PERL__ section of a page via the "use" or "require" functions).

Using WebDyne::Chain you can modify the behaviour of WebDyne pages based on their location. The WebDyne::Template module can be used in such scenario to wrap all pages in a location with a particular template. Another would be to make all pages in a particular location static without loading the WebDyne::Static module in each page:

<Location /static>

#  All pages in this location will be generated once only.
PerlHandler     WebDyne::Chain
PerlSetVar      WebDyneChain    'WebDyne::Static'

</Location>

Multiple modules can be chained at once:

<Location />

#  We want templating and session cookies for all pages on our site.
PerlHandler     WebDyne::Chain
PerlSetVar      WebDyneChain    'WebDyne::Session WebDyne::Template'
PerlSetVar      WebDyneTemplate '/path/to/template.psp'

</Location>

The above example would place all pages within the named template, and make session information to all pages via $self->session_id(). A good start to a rudimentary CMS.

WebDyneChain

Directive. Supply a space separated string of WebDyne modules that the request should be passed through.

WebDyne::Static

Loading WebDyne::Static into a __PERL__ block flags to WebDyne that the entire page should be rendered once at compile time, then the static HTML resulting from that compile will be handed out on subsequent requests. Any active element or code in the page will only be run once. There are no API methods associated with this module

See the "Static Sections" reference for more information on how to use this module within an individual page.

WebDyne::Static can also be used in conjunction with the

          "[WebDyne::Chain](07_extending_webdyne.md#webdyne_chain)"
         module to flag all files in a directory

or location as static. An example httpd.conf snippet:

<Location /static/>

PerlHandler     WebDyne::Chain
PerlSetVar      WebDyneChain    'WebDyne::Static'

</Location>

WebDyne::Cache

Loading WebDyne::Cache into a __PERL__ block flags to WebDyne that the page wants the engine to call a designated routine every time it is run. The called routine can generate a new UID (Unique ID) for the page, or force it to be recompiled. There are no API methods associated with this module.

See the "Caching" section above for more information on how to use this module with an individual page.

WebDyne::Cache can also be used in conjunction with the

          "[WebDyne::Chain](07_extending_webdyne.md#webdyne_chain)"
         module to flag all files in a

particular location are subject to a cache handling routine. An example httpd.conf snippet:

<Location /cache/>

#  Run all requests through the MyModule::cache function to see if a page should
#  be recompiled before sending it out
#
PerlHandler     WebDyne::Chain
PerlSetVar      WebDyneChain    'WebDyne::Cache'
PerlSetVar      WebDyneCacheHandler '&MyModule::cache'

</Location>

Note that any package used as the WebDyneCacheHandler target should be already loaded via "PerlRequire" or similar mechanism.

As an example of why this could be useful consider the "caching examples" above. Instead of flagging that an individual file should only be re-compiled every x seconds, that policy could be applied to a whole directory with no alteration to the individual pages.

WebDyne::Session

WebDyne::Session generates a unique session ID for each browser connection and stores it in a cookie. It has the following API:

session_id()

Function. Returns the unique session id assigned to the browser. Call via $self->session_id() from perl code.

$WEBDYNE_SESSION_ID_COOKIE_NAME

Constant. Holds the name of the cookie that will be used to assign the session id in the users browser. Defaults to "session". Set as per "WebDyne::Constants" section. Resides in the WebDyne::Session::Constant package namespace.

Example:

<start_html>

Session ID: !{! shift()->session_id() !}

<end_html>

__PERL__

use WebDyne::Session;
1;

Run

WebDyne::Session can also be used in conjunction with the

          "[WebDyne::Chain](07_extending_webdyne.md#webdyne_chain)"
         module to make session information

available to all pages within a location. An example httpd.conf snippet:

<Location />

# We want session cookies for our whole site
#
PerlHandler     WebDyne::Chain
PerlSetVar      WebDyneChain    'WebDyne::Session'

#  Change cookie name from "session" to "gingernut" for something different
#
PerlSetVar      WEBDYNE_SESSION_ID_COOKIE_NAME    'gingernut'

</Location>

WebDyne::Template

One of the more powerful WebDyne extensions. WebDyne::Template can be used to build CMS (Content Management Systems). It will extract the <head> and <body> sections from an existing HTML or WebDyne page and insert them into the corresponding head and body blocks of a template file.

The merging is done once at compile time - there are no repeated search and replace operations each time the file is loaded, or server side includes, so the resulting pages are quite fast.

Both the template and content files should be complete - there is no need to write the content without a <head> section, or leave out <html> tags. As a result both the content and template files can be viewed as standalone documents.

The API:

template ( filename )

Function. Set the file name of the template to be used. If no path is specified file name will be relative to the current request directory

WebDyneTemplate

Directive. Can be used to supply the template file name in a Apache or lighttpd/FastCGI configuration file.

Example:

The template:

<html>

<head>
<block name="head" display="1">
<title>Template</title>
</block>
</head>

<body>

<table width="100%">

<tr>
<td colspan=2 bgcolor="green">
<span style="color:white;font-size:20px">Site Name</span>
</td>
</tr>

<tr>
<td bgcolor="green" width="100px">
<p>
Left
<p>
Menu
<p>
Here
</td>

<td bgcolor="white">

<!-- Content goes here -->
<block name="body" display="1">
This is where the content will go
</block>

</td>
</tr>

<tr>
<td colspan=2 bgcolor="green">
<span style="color:white">
<perl method="copyright">
Copyright (C) ${year} Foobar corp.
</perl>
</span>
</td>
</tr>


</table>

</body>
</html>

__PERL__

sub copyright {

    shift()->render(year=>((localtime)[5]+1900));

}

Run

The content, run to view resulting merge:

<html>
<head><title>Content 1</title></head>

<body>
This is my super content !
</body>

</html>

__PERL__

use WebDyne::Template qw(template1.psp);

Run

In real life it is not desirable to put the template name into every content file (as was done in the above example), nor would we want to have to "use WebDyne::Template" in every content file.

To overcome this WebDyne::Template can read the template file name using the Apache dir_config function, and assign a template on a per location basis using the WebDyneTemplate directive. Here is a sample httpd.conf file:

<Location />

PerlHandler     WebDyne::Chain
PerlSetVar      WebDyneChain    'WebDyne::Template'
PerlSetVar      WebDyneTemplate '/path/to/template.psp'

</Location>