NAME

Modwheel - Tree-based Web framework.

VERSION

This document describes Modwheel version 0.3.3

DESCRIPTION

Most web sites are pages categorized by topic. So web sites can be viewed as a tree system where every page is a sub-tree and the page elements are nodes. Page elements can be things like articles, links, ads, news, comments and so on. In Modwheel a page-element is called an object. You define your own object prototypes and then you define how to display these objects with the representation engine. Objects can be displayed differently in different contexts (pages) by using templates. The only representation engine supported right now is the Template Toolkit, but it wouldn't be much work to add support for others. The project is in beta development stage but already has an admin interface implemented in it and has been tested on Mac OS X, FreeBSD, OpenBSD, NetBSD, Ubuntu Linux, Solaris and Cygwin.

The current development version of Modwheel should work with MySQL, SQLite2 and the Template Toolkit, although porting to other databases or templating systems. shouldn't be much work. (Actually the SQLite2 port took less than 30 minutes).

SYNOPSIS

    #!/usr/bin/perl -T
    use strict;
    use warnings;
    use Modwheel::Session;
    use IO::Handle;
    use CGI;
    *STDOUT->autoflush( );

    my $modwheel_config = {
        site            => 'modwheeltest',
        locale          => 'en_EN',
        logmode         => 'stderr',
    };

    my ($modwheel, $db, $user, $object, $template) =
        modwheel_session($modwheel_config, qw(db user template object));

    $db->connect or exit;

    # A user-session can also be created, if there is none, the session is anonymous.
    #$user->login($username, $password);

    # The page is the page to process, it has to be in the templatedir directory.
    my $page           = shift @ARGV || 'index.html';
    my $directory_id   = $db->path_to_id($directory_path);
    $directory_id    ||= Modwheel::Object::MW_TREE_ROOT;

    my $cgi = new CGI;

    $template->init(input => $page, parent => $directory_id, param => $cgi);
    print $template->process();

    $db->disconnect;

SUBROUTINES/METHODS

CONSTRUCTOR

`Modwheel->new()`

Creates a new Modwheel object.

Arguments:

It requires a hash of configuration options as argument. The configuration keys are:

    prefix         - The base Modwheel directory. (i.e /opt/modwheel)
    configfile     - Name of the configuration file. (i.e config/modwheelconfig.yml)
    logmode        - Where log messages goes. Can be stderr, off or you can
                     install your own loghandler with install_loghandler().
    site           - The site to use. Must have a corresponding site directive in the config file.
    locale         - The locale to use. (i.e en_EN)
    debug          - Turn on debugging features.    
    logobject      - A object that can be used in your loghandler for logging.

Returns:

A new Modwheel object if everything was OK. Returns no value if there was an error.

ATTRIBUTES

`$modwheel->debug()`

`$modwheel->set_debug()`

If this is on (set to a true value), the modwheel components will print various debugging messages. Turn this off for production environments as it can reveal sensitive information.

`$modwheel->logmode()`

How to log errors and warnings.

`$modwheel->set_logmode($mode)`

Sets the current logmode. Default log modes are: stderr and off. Modwheel-Apache installs the log mode: apache2 If logmode is off no logging will happen, but error() will still be set on error.

`$modwheel->prefix()`

`$modwheel->set_prefix($prefix)`

The path to search for relative files.

%{`$modwheel->config()`}

The configuration data structure returned by YAML. Returns hash reference.

`$modwheel->set_config($href)`

Save the configuration data structure. You rarely want to use this.

`$modwheel->configfile()`

`$modwheel->set_configfile($filename)`

The YAML configuration file to use. For more information about YAML please see: http://www.yaml.org.

`$modwheel->site()`

`$modwheel->set_site($site)`

The name of the current site to use. This is the name used when getting site configuration with siteconfig(). If no site is specified, it uses the defaultsite specified in the global section of the configuration.

`$modwheel->logobject()`

`$modwheel->set_logobject($your_object)`

If you install a log handler with $modwheel->install_loghandler() you save a object here for use within your log handler.

`$modwheel->error()`

Holds the last error string passed to log().

`$modwheel->locale()`

Current locale in use.

INSTANCE METHODS

`$modwheel->locale_setup_with_locale($locale)`

Sets the current locale using POSIX::setlocale.

`$modwheel->locale_setup_from_config()`

If no custom locale is passed when creating a Modwheel object, it sets up the locale using either the locale specified in the current siteconfig or the locale specified in the global section of the configuration file.

`$modwheel->siteconfig()`

Returns the current siteconfig using the site name in $self-site>.

`$modwheel->install_loghandler($name, $code_ref)`

Installs new log handler, $code_ref must be an anonymous subroutine.

This is and example how Apache2-Modwheel can make an handler to log messages with the apache2 request object's Apache2::Log::log_error();

    my $log_handler_ref = sub {
        my ($modwheel, $log_string) = @_;
        my $apache2_request = $modwheel->logobject;
        $apache2_request->log_error( $log_string );
        return;
    }
    $modwheel->set_logobject($r);
    $modwheel->install_handler('apache2', $log_handler_ref);
    $modwheel->logmode('apache2');

Or to install the handlers when calling Modwheel->new

    my $modwheel = Modwheel->new(
        # [....]
        logobject       => $r,
        add_loghandlers => {
            apache2         => $log_handler_ref;
        },
        logmode         => 'apache2',
        # [....]

`$modwheel->remove_loghandler($name)`

Remove a log handler previously installed with ->install_loghandler().

`$modwheel->parseconfig()`

Example:

    $modwheel->set_config("/opt/modwheel/testconfig.yml");
    my $config = $modwheel->parseconfig();
    $modwheel->set_config($config);

We use YAML for parsing our configuration file specified in configfile(). Exits if the configuration file does not exist. Returns: Hashref to the data structure returned by YAML::LoadFile.

`$modwheel->dumpconfig()`

Dumps a scalar string representation of the configurations YAML data structure.

`$modwheel->logerror(@strings)`

Log an error.

`$modwheel->logwarn(@strings)`

Log a warning.

`$modwheel->loginform(@strings)`

Log some informative text.

`$modwheel->log(string facility, string logstr)`

The private logging function, shouldnÕt be used directly. Use the logerror/logwarn/loginform functions instead.

`$modwheel->throw($exception)`

Throw an exception. Adds the exception to the exceptions array.

`$modwheel->exception()`

Pop a exception off the exceptions array.

`$modwheel->catch($exception)`

Search the exceptions array for an exception. Returns 1 if found and 0 if not found.

`$modwheel->catch_like($regex)`

Like catch() but searches the exceptions array by using regular expression.

PRIVATE ATTRIBUTES AND METHODS

`$modwheel->set_error()`

Set the error message. This is a private function, use the log* methods instead.

@{ `$modwheel->exceptions()` }

This is the internal array used by the exceptions system. Use $modwheel->throw(), $modwheel->catch(), $modwheel->catch_like() and $modwheel->exception() instead.

`$modwheel->_setlocale($locale)`

Internal method for setting locale. Use locale_setup_with_locale($locale) instead.

CONFIGURATION AND ENVIRONMENT

Modwheel requires a configuration file in the YAML format. For more info on the configuration syntax see the manual:

Modwheel::Manual::Config

DIAGNOSTICS

The modwheel test suite.

DEPENDENCIES

Perl >= 5.8
version
namespace::clean
Params::Util
List::MoreUtils
Readonly
Perl6::Export::Attrs
YAML::Syck
DBI
Crypt::Eksblowfish
HTML::Tagset
HTML::Parser
URI::Escape
Template

INCOMPATIBILITIES

None known at the moment.

BUGS AND LIMITATIONS

None known at the moment.

DSLIP

    b   - Beta testing
    d   - Developer: asksh@cpan.org
    p   - Perl-only
    O   - Object oriented
    p   - Standard-Perl: user may choose between GPL and Artistic.

COVERAGE

Devel::Cover does not tell us anything about the quality of our code, tests or documentation, but it's a good way to spot critical areas that needs attention. The goal is to get atleast 90% coverage for all classes. As you can see POD-documentation is not entirely covered yet, but documentation for all methods is beeing written and the goal for 90% coverage should be met in the nearest future.

This is the current output from Devel::Cover:

    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    File                           stmt   bran   cond    sub    pod   time  total
    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    ...ideOut/Policy/Modwheel.pm   45.2   20.2   20.7   58.8    0.0    5.3   39.0
    lib/Modwheel.pm               100.0   95.7   75.0  100.0  100.0    1.3   97.8
    lib/Modwheel/DB.pm            100.0  100.0  100.0  100.0  100.0    0.1  100.0
    lib/Modwheel/DB/Base.pm        82.9   68.4   57.1   80.9   93.9    5.3   79.2
    lib/Modwheel/DB/MySQL.pm      100.0  100.0    n/a  100.0  100.0    0.1  100.0
    ...Modwheel/DB/PostgreSQL.pm   40.0    0.0    0.0   54.5   80.0    0.0   39.4
    lib/Modwheel/HTML/Tagset.pm    99.1   97.1  100.0  100.0  100.0    0.4   98.8
    lib/Modwheel/Instance.pm      100.0  100.0    n/a  100.0   50.0    0.2   97.8
    lib/Modwheel/Object.pm         96.1   88.0   83.3   97.9   82.1    2.4   93.0
    lib/Modwheel/Repository.pm     36.2   22.9   17.6   76.5    0.0    0.6   34.2
    lib/Modwheel/Session.pm       100.0   60.0   40.0  100.0    n/a    0.1   84.9
    lib/Modwheel/Template.pm      100.0  100.0    n/a  100.0  100.0    0.1  100.0
    ...l/Template/ObjectProxy.pm  100.0  100.0  100.0  100.0  100.0    0.1  100.0
    ...eel/Template/Shortcuts.pm   92.2   88.5   66.7  100.0  100.0    0.2   91.8
    lib/Modwheel/Template/TT.pm   100.0   94.4   62.5  100.0    0.0    0.3   94.1
    ...eel/Template/TT/Plugin.pm   19.4    6.2    0.0   25.9    2.1    0.1   16.2
    lib/Modwheel/User.pm           98.4   93.2  100.0  100.0    0.0   83.5   93.6
    Total                          74.6   62.5   56.9   78.3   51.2  100.0   70.7
    ---------------------------- ------ ------ ------ ------ ------ ------ ------

AUTHOR

Ask Solem, ask@0x61736b.net.

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 781:: Non-ASCII character seen before =encoding in 'shouldnÕt'. Assuming CP1252

To install Modwheel, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Modwheel

CPAN shell

perl -MCPAN -e shell
install Modwheel

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

DESCRIPTION

SYNOPSIS

SUBROUTINES/METHODS

CONSTRUCTOR

Modwheel->new()

ATTRIBUTES

$modwheel->debug()

$modwheel->set_debug()

$modwheel->logmode()

$modwheel->set_logmode($mode)

$modwheel->prefix()

$modwheel->set_prefix($prefix)

%{$modwheel->config()}

$modwheel->set_config($href)

$modwheel->configfile()

$modwheel->set_configfile($filename)

$modwheel->site()

$modwheel->set_site($site)

$modwheel->logobject()

$modwheel->set_logobject($your_object)

$modwheel->error()

$modwheel->locale()