root / veekun / trunk / README.pod

=pod

=head1 INTRODUCTION

Welcome to the veekun codebase!  This is the magical mystical melting pot of
Perl that somehow keeps http://veekun.com running.

=head1 GETTING STARTED

For the most part, this code should run as-is with very little setup.  However,
there are two dependencies you will need to take care of first: Perl modules
and the database.

=head2 Perl Modules

You will need the following modules installed to run this code.  This list is
not exhaustive, as I am typing it off the top of my head and making no effort
to confirm it whatsoever.

    Catalyst
    Catalyst::Model::DBIC
    Catalyst::Model::DBIC::Schema
    Catalyst::View::TT
    Catalyst::Plugin::Authentication
    Catalyst::Plugin::Authentication::Store::DBIC
    Catalyst::Plugin::ConfigLoader
    Catalyst::Plugin::Session
    Catalyst::Plugin::Session::State::Cookie
    Catalyst::Plugin::Session::Store::DBIC
    Catalyst::Plugin::Unicode
    DBIx::Class
    DBIx::Class::QueryLog
    DateTime
    Email::Valid
    Image::Size
    JSON
    List::MoreUtils
    List::Util (part of Scalar-List-Utils)
    String::Approx
    Template
    Time::Out
    XML::Feed
    YAML

Additionally, you may want the following modules if you plan to do any heavy
development.

    Catalyst::Devel
    Catalyst::Plugin::StackTrace
    Catalyst::Plugin::Static::Simple

=head2 Database Setup

All you need to do is create a database (or even reuse an old one, as long as
you aren't worried about naming clashes) and load each of the .sql files in the
script/ directory, as described below in L<script/>.  The F<base_data.sql> file
contains very minimal test data; enough to ensure every page will display.  A
dummy administrator login of C<admin:password> is included; I suggest you not
leave it there any longer than necessary.

I have been using MySQL and have not tested the code on any other database, but
as long as you change the database driver in vee.yml and manage to import the
table definitions, any other database should be fine.

=head2 File Setup

If you want to generate the downloads at L</dex/resources>, run the script
F<script/create_downloads.pl>.  You will need to have tar, gzip, ImageMagick,
and pngcrush available.

=head2 Running

The easiest way to get veekun on the Web is just to run F<script/vee_server.pl>
(although you may have to manually use perl; the shebang line was generated on
a Windows box).  This will start the built-in Catalyst server on port 3000.

=head1 CODE LAYOUT

=head2 lib/

All of the actual site's Perl code is stashed in here, arranged as normal for a
Catalyst app.  The main namespace is C<Vee::>.  Controllers (i.e. the bulk of
the code) are under C<Vee::Controller::>, a small View module that serves as a
glue to Template Toolkit is in C<Vee::Controller::TT>, and class wrappers for
database tables reside in C<Vee::Model::>.  C<Vee::Schema> is a tiny database
glue class.  Other modules are extra bits of useful code that don't really fit
the regular Catalyst structure.

=head2 root/

Root of the filesystem, where static files live.  As a general rule, anything
static should go into one of the existing folders, to make it easier to run
veekun without C<Static::Simple>.

=head2 script/

This folder contains scripts that are not actually part of the veekun code, are
are not ever called by any veekun code, and are not actually necessary for the
operation of veekun.  Since looking through all of them to find out whether or
not they are necessary would be a colossal waste of time, their functions are
documented here.

=head3 dump_sql.pl and *.sql

The Perl script is a simple wrapper around mysqldump that will produce a .sql
file for some chunk of the database.  It will read database, user, and password
information from the main Catalyst configuration file.  It can take table
group names as arguments; the groups are rather clearly/obviously defined in
the script if you are really curious. These .sql files are in the repository
and are used to track the structure of the database.  The Pokedex script dumps
all the table data, whereas the others only dump table structure; there is,
however, some very minimal starting data in F<base_data.sql>.

If you change the structure of the database, please remember to also run the
corresponding dump script so that you can commit the change.

=head3 vee_*.pl

These are startup scripts generated by Catalyst for running the code under
various engines.  C<vee_server.pl> is the Catalyst standalone server and best
suited for development or testing.  The others are fairly self-explanatory, and
the Catalyst documentation will tell you which one you need depending on which
engine you are trying to use.

=head2 static/

Static Template Toolkit templates that are used when a URL with no matching
controller is requested -- i.e., a request for F</a/b/c> with no controller
named C<A> will try to return F</static/a/b/c.tt>.  If no static template is
found, of course, the client will get a 404.

=head2 t/

Auto-generated Catalyst tests.  I haven't written any real ones of my own yet
because I am a terrible person.  I am sorry; maybe I will get around to it
sometime.

=head2 templates/

Template Toolkit templates.  More or less matches the URL structure, although
not necessarily exactly.  There are a few 'include' templates, too, all named
F<common.tt> or similar.

=cut