NAME

AnnoCPAN::Control - Main AnnoCPAN Web Interface Control Module

SYNOPSIS

    # in the simplest case, this is all you need...
    use AnnoCPAN::Control;
    AnnoCPAN::Control->new->run;

DESCRIPTION

This is the main module that handles the AnnoCPAN web application. It handles getting the CGI parameters, running the appropriate handlers, and making sure that the appropriate templates are processed.

METHODS

$class->new(%options)

Create a new AnnoCPAN control object. Options:

 cgi => cgi object
 tt  => template object

$obj->run

Process the request. This includes figuring out the runmode, checking if the user is logged in, running the handler, printing the headers, and processing the template.

$obj->mode

Return the runmode. Runmodes must be made of word characters, begin with an uppercase letter, and be a method in $obj.

$obj->cgi

Returns the CGI object.

$obj->tt

Returns the Template object.

$obj->param(@_)

Get CGI parameters. Delegated to $self->cgi.

$obj->header(@_)

Return HTTP headers as a string. Delegated to $self->cgi.

$obj->redirect($uri)

Print a 303 HTTP redirect header, including the cookies in $obj->cookies.

$obj->process($template_file, \%vars [, \$ret])

Process a template. Delegated to $self->tt.

$obj->default_vars

Return a hashref with the default template variables, common to all runmodes (for example, the user object).

$obj->prefs($pref_name)

Returns the value for a given user preference.

$obj->cookies

Return an arrayref with the current cookies (which are CGI::Cookie objects).

$obj->add_cookie($name, $value)

Create a cookie. It will be later pushed to the client with the HTTP headers, and it is immediately available via $obj->cookies.

$obj->delete_cookie($name)

Issue an expired cookie with a given name, forcing the client to forget it (one use is for logging out).

$obj->check_login

Check if the user is logged in (by checking the login, time, and key cookies); Returns an AnnoCPAN::DBI::User object if logged in, or false if not.

$obj->set_login_cookies($user)

Creates the login cookies for $user (which should be an AnnoCPAN::DBI::User object).

$obj->user($user)

May be used to set an arbitrary user (to force a login). If no $user is provided (and none has been provided before), returns whatever check_login would return (a user object or false).

$obj->key($login, $time)

Returns a login key as a string. Depends on the "secret" configuration option.

Runmode methods

A runmode method has the following characteristics:

1) Its name matches /[A-Z]\w+/

2) Returns a list ($vars, $template, $type). $vars is a hash reference of variables that should be passed to the template; $template is the name of the template that should be processed (sans the extension). $type is the MIME type that should be given in the header. $type is optional; it defaults to text/html. If $template is false, no headers will be printed and no template will be processed.

3) Takes an optional parameter $vars. If given, it is expected to be a hash reference which will be appended to the variables normally returned by the method. It is used when one mode decides to fall back to another but wants to add or override some variables of its own.

For example, the Main method could be:

    sub Main {
        my ($self, $vars) = @_;
        $vars ||= {};
        my @recent = AnnoCPAN::DBI::Note->search_recent;
        ({recent => \@recent, %$vars}, "main");
    }

Warning: the documentation below may be slighly incomplete or outdated:

$obj->Main($vars)

The front page. Provides the "recent notes" list.

$obj->Show($vars)

Displays one POD page. Uses the pid CGI parameter.

$obj->Show_note

Displays the POD page that is the "main reference" for a given note. Uses the id CGI parameter.

$obj->Show_dist($vars)

Displays one distribution (distver) page. Uses the id CGI parameter or $vars->{distver}.

$obj->Edit

The edit screen (like Show, but includes the edit form).

$obj->About

The "about" page. Uses the about.pod file.

$obj->Save

Save a new note (comes from the Edit mode). Uses the pid, pos, id, and note CGI parameters.

$obj->New_user

"Create new user" screen.

$obj->Create_user

Coming from the New_user form, create a new account. Uses the login, passwd, passwd2, and email CGI parameters. Checks that the login and password are not blank, that the passwords match, and that the login is not already taken.

$sub->Login

Log in; comes from the login form on login_form.html. Uses the login and passwd CGI parameters.

$obj->Logout

Log out. Clears the authentication key.

SEE ALSO

AnnoCPAN::DBI, AnnoCPAN::Config

AUTHOR

Ivan Tubert-Brohman <itub@cpan.org>

COPYRIGHT

Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.