The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Rubric-0.01
River stage zero No dependents
4 ++
/ Rubric::WebApp

NAME

Rubric::WebApp - the web interface to Rubric

VERSION

version 0.01

 $Id: WebApp.pm,v 1.53 2004/12/16 14:06:34 rjbs Exp $

SYNOPSIS

 use strict;
 use warnings;
 use Rubric::WebApp;
 Rubric::WebApp->new->run();

It's a CGI::Application!

DESCRIPTION

Rubric::WebApp provides a CGI-based interface to Rubric data. It's built on top of CGI::Application, which does most of the boring work. This module's code sets up the dispatch tables and implements the responses to various queries.

REQUESTS DISPATCH

Requests are mostly path-based, though some involve form submission. The basic dispatch table looks something like this:

 request      | description                               | method called
 -------------+-------------------------------------------+--------------
 /login       | log in to a user account                  | login
 /logout      | log out                                   | logout
 /preferences | view or change account settings           | preferences
 /newuser     | create a new user account                 | newuser
 /verify      | verify a pending user account             | verify
 /link        | view the details of entries for a link    | link
 /post        | post or edit an entry (must be logged in) | post
 /edit        | edit an entry (must be logged in)         | edit
 /delete      | delete an entry (must be logged in)       | delete
 /recent      | see recent entries                        | recent
 /user/NAME   | see a user's entries                      | user
 /user/N/TAGS | see a user's entries for given tags       | user
 /tag/TAGS    | see entries for given tags                | tag
 /doc/PAGE    | view the named page in the documentation  | doc

If the system is private and no user is logged in, the default action is to display a login screen. If the system is public, or a user is logged in, the default action is to display recent entries.

METHODS

redirect($uri, $message)

This method simplifies redirection; it redirects to the given URI, printing the given message as the body of the HTTP response.

redirect_root($message)

This is shorthand to redirect to the Rubric's root URI. It calls redirect.

cgiapp_init

This method is called during CGI::Application's initialization. It finds (or creates) a CGI::Session, checks for a login, checks for updates to result-set paging, and starts processing the request path.

check_for_login

This method is called by cgiapp_init, and checks for a login attempt in the submitted request. A login request is made with two CGI parameters:

 user     - the user's username
 password - the user's password

If these match, the user is now logged in. If not, it is ignored.

However! If the REMOTE_USER environment variable is set, because the user has logged in via HTTP, the value of REMOTE_USER is used as the current user.

get_current_user

This method is called by cgiapp_init, and retrieves the Rubric::User object for the currently logged-in user, if any.

check_pager_data

This method is called by cgiapp_init, and sets up parameters used for paging entry listings. The following parameters are used:

 per_page - how many items per page; default 25, maximum 100; stored in session;
 page     - which page to display; default 1

template($template, \%variables)

This method is used to render a template with both provided and default variables.

Templates are rendered by calling the process method on the template renderer, which is retrieved by calling the renderer method on the WebApp.

The following variables are passed by default:

 current_user - the currently logged-in user (a Rubric::User object)
 per_page     - entries per page (see check_pager_data)
 page         - which page (see check_pager_data)

setup

This method, called by CGI::Application's initialization process, sets up the dispatch table for requests, as described above.

entry

This displays the single requested entry.

get_entry

This method gets the next part of the path, assumes it to be a Rubric::Entry id, and puts the corresponding entry in the "entry" parameter.

This runmode displays entries that point to a given link, identified either by URI or MD5 sum.

This method look for a uri or, failing that, url query parameter. If found, it finds a Rubric::Link for that URI and puts it in the "link" parameter.

login

If the user is logged in, this request is immediately redirected to the root of the Rubric site. Otherwise, a login form is provided.

logout

This run mode unsets the "current_user" parameter in the session and the WebApp object, then redirects the user to the root of the Rubric site.

preferences

This method displays account information for the current user. Some account settings may be changed.

newuser

If the proper form information is present, this runmode creates a new user account. If not, it presents a form.

If a user is already logged in, the user is redirected to the root of the Rubric.

verify

This runmode attempts to verify a user account. It expects a request to be in the form: /verify/username/verification_code

user

This method will find the user requested (the name after "/user/" in the path) and note it in the request. The request is then redispatched to the tag method.

tag

This method notes the requested tags (the words after /tag or /user/NAME in the path) and redispatches to display_entries.

recent

This method uses page_entries and render_entries to display the most recent entries for all users and tags.

This should probably be what happens when display_entries is called with no search criteria in place.

display_entries

This method searches (with Rubric::Entry) for entries matching the requested user and tags. It pages the result (with page_entries) and renders the resulting page with render_entries.

page_entries($iterator)

Given a Class::DBI::Iterator, this method sets up parameters describing the current page. Most importantly, it retrieves an Iterator for the slice of entries representing the current page. The following parameters are set:

 entries - a Class::DBI::Iterator for the current page's entries
 count   - the number of entries in the entire set
 pages   - the number of pages the set spans

render_entries

This method renders a template to display the set of entries set up by page_entries.

edit

If the user isn't logged in, it redirects to demand a login. If he is, it displays a post form, completed with the given entry's data.

post

This method wants to be simplified.

If the user isn't logged in, it redirects to demand a login. If he is, it checks whether it can create a new entry. If so, it tries to. If not, it displays a form for doing so. If the user already has an entry for the given URI, the existing entry is passed to the form renderer.

If a new entry is created, the user is redirected to his entry listing.

post_form

This method renders a form for the user to create a new entry.

must_login

This method renders a form for the user to create a new entry.

delete

This method wants to be simplified. It's largely copied from post.

If the user isn't logged in, it redirects to demand a login. If he is, it checks whether the user has an entry for the given URI. If so, it's deleted.

Either way, the user is redirected to his entry listing.

doc

This runmode returns a mostly-static document from the template path.

get_doc

This gets the next part of the path and puts it in the doc_page parameter.

TODO

  • change email, password

AUTHOR

Ricardo SIGNES, <rjbs@cpan.org>

BUGS

Please report any bugs or feature requests to bug-rubric@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT

Copyright 2004 Ricardo SIGNES. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.