Name

Web::VWF - Versatile Web Framework - easily build a website to support different languages and client platforms

Version

Version 0.003.0

Synopsis

A site's page script, cgi-bin/page.fcgi, is all of this:

    use FindBin;
    use Web::VWF;

    Web::VWF->new({ directory => "$FindBin::Bin/../conf" })->run();

Description

Web::VWF is VWF, the Versatile Web Framework, packaged as a CPAN distribution. It is an MVC framework for building responsive websites that adapt to the client's language, to the kind of client (web, mobile, robot, search engine or AI crawler) and to whichever database back end the site uses.

This module is the distribution's front door: it holds the version number, this overview, and the one thing a site builds by hand - "new", the site's configuration and the directory the server keeps it in. Working the framework does these modules:

example/ in this distribution is a small working site to copy and adapt: example/cgi-bin/page.fcgi is the page script, example/conf/default is the configuration (placeholders only - put real keys in your own copy), and example/templates/ holds the templates. Run it from the command line with CONFIG_DIR=$(pwd)/example/conf root_dir=$(pwd)/example perl -Ilib example/cgi-bin/page.fcgi page=index.

A site's templates sit under a path built from the page's class name, so the file to change when the page module is Web::VWF::Display::index is templates/web/Web/VWF/Display/index.tmpl - see Web::VWF::Display for the rest of the search order.

A site that used to carry a renamed copy of VWF of its own deletes that copy, installs this distribution, renames VWF:: to Web::VWF:: in its own code, and moves its templates from .../VWF/Display/ to .../Web/VWF/Display/.

Configuration

A site is configured by files, usually XML, in its conf/ directory (see Web::VWF::Config for where they are looked for, in which order, and how an environment variable of the same name as a top-level key overrides that key). The file named default is read first, then one named for the site's domain name, then $CONFIG_FILE. example/conf/default is a complete working example.

Every setting is optional. What a site does not say gets the default given below, which is what the framework did before the setting existed.

Environment Variables

Pages: Display

    <display>
            <directory>/path/to/modules</directory>
            <page>
                    <name>states</name>
                    <description>Displays information about the U.S. states</description>
                    <directory>/path/to/this/page</directory>
            </page>
    </display>

One page for each page that ?page= may name. The name is required and may only be word characters. The description is shown in the 300 Multiple Choices response, which lists the pages when no page is given. A page is the class Web::VWF::Display::<name> and its template.

directory says where the page modules are. In display it is the default for all of them, in a page it is that page's alone and wins. It is where the <name>.pm file is, not a directory of templates. A relative one is taken from the directory the page script is in. A page with no directory at all is found in @INC.

With no page at all, display's directory is searched and every .pm in it, except captcha.pm, is a page. With no display either, that is ../lib/Web/VWF/Display beside the script.

The old pages is read when there is no display, as is its old form of one string of names, <pages>index, meta_data</pages>.

Data: Databases

    <databases>
            <directory>/path/to/modules</directory>
            <database>
                    <name>states</name>
                    <description>List of data about the U.S. states</description>
                    <directory>/path/to/this/module</directory>
            </database>
    </databases>

One database for each data module a page may use. A page is given each as a variable named for the last part of its class, lower-cased: the module Web::VWF::Data::states is $states in the page. A name with no :: in it is a Web::VWF::Data:: module; one with ::, such as Bands::Data::bands, is used as written. The description is only logged.

directory is where the module's .pm file is, in the same way as for display, named for the last part of the class. It is not where the database's own files are: that is database_dir.

What is loaded, in order of preference:

A module that cannot be loaded is logged and skipped; the pages that do not need it still work.

This is not called data because the data modules are given the configuration's top-level keys as their constructor arguments, and a key called data replaces the rows of every database.

Other Settings

List-valued settings (supported_languages, allow_ips, rate_limit_trusted_ips, blacklist_countries) may be written as one string separated by commas or spaces, or as an element with one child for each value.

Recaptcha

    <recaptcha>
            <enabled>1</enabled>
            <site_key>...</site_key>
            <secret_key>...</secret_key>
    </recaptcha>

Google reCAPTCHA, from https://www.google.com/recaptcha/admin. When it is enabled a client past the soft rate limit is shown a challenge instead of being refused. When it is not, the hard limit refuses with a plain-text 429.

Security

Throttle

The per-address throttle used by Web::VWF::Allow and by Web::VWF::Display, which share one file.

Caches: disc_cache and memory_cache

    <disc_cache>
            <driver>File</driver>
            <root_dir>/var/tmp/cache</root_dir>
    </disc_cache>

The CHI caches. driver is one of Memory, BerkeleyDB, DBI, Redis, Memcached, SharedMem, File or Null. Default for disc_cache: BerkeleyDB, or File where that is not installed; for memory_cache: Memory. The other keys depend on the driver:

Subroutines/Methods

New

The configuration of a site, and the directory the server keeps it in.

Parameters:

Api Specification

Input
    {
            directory => { type => 'string', optional => 1 },
            info => { type => 'object', optional => 1 },
            logger => { type => 'object', optional => 1 },
            config_directory => { type => 'string', optional => 1 },
            config_file => { type => 'string', optional => 1 },
            config => { type => 'hashref', optional => 1 },
    }

new croaks with directory must be a string when directory is a reference.

Output
    { type => 'object', isa => 'Web::VWF' }

Run

Serve requests. It accepts FastCGI requests one after another and sends each one to the page named by ?page=, as described in "DESCRIPTION"; an error in one request is logged and does not end the worker.

The loop ends, and run returns, when the web server asks the worker to exit, after a TERM or USR1 signal, or when the page script has been changed since the worker started, so that the next request starts a worker with the new code.

When REMOTE_ADDR is not set, which is how the script is run from a command line, there is no web server: run handles one request, built from the command-line arguments such as page=index, turns caching off, takes the language from LANG and prints debug logging to STDOUT among the response.

run refuses to run again from inside itself, and to run while the script is still being compiled, which happens when something reads the page script as if it were a configuration file. It prints a message on STDERR and returns.

Api Specification

Input
    {}
Output
    { type => 'undef' }

_Directory

Internal: not part of the public interface. The directory the server keeps this site's configuration in: what new() was given, or /usr/lib/vwf. Web::VWF::Config adds the site's own name to it.

Api Specification

Input
    {}
Output
    { type => 'string' }

_Config

Internal: not part of the public interface. The site's configuration, read once and kept: a site that has no conf/ of its own beside cgi-bin/ is configured from the server's directory for it, and Web::VWF::Config describes the rest of the search.

Api Specification

Input
    {}
Output
    { type => 'object', isa => 'Web::VWF::Config' }

Author

Nigel Horne, <njh at nigelhorne.com>

Copyright 2010-2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.