[Openinteract-commits] CVS: OpenInteract2/doc/Manual API.pod,NONE,1.1

[Chris W. <la...@us...>]

Update of /cvsroot/openinteract/OpenInteract2/doc/Manual
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv5594/doc/Manual

Added Files:
	API.pod 
Log Message:
OIN-46: add API guideline document

--- NEW FILE: API.pod ---
=head1 NAME

OpenInteract2::Manual::API - API guidelines for OpenInteract2

=head1 SYNOPSIS

This document will provide an overview of the different APIs in
OpenInteract2 -- configuration, templating and interfaces, logging,
coding, etc. -- and provide recommended uses.

=head1 CONFIGURATION

=head2 INI files everywhere

Where possible OpenInteract2 uses configuration in a slightly
customized INI format. You can learn details of this format in the
module that does the parsing (L<OpenInteract2::Config::Ini>) but it's
useful to put a few usage guidelines here.

=head2 Defining lists

Our custom INI format has different ways to define lists. You can just
use the key multiple times:

 [mysection]
 key = value
 key = value2
 key = value3

But since some configuration keys take a lot of values this can make
for a very long configuration file. As an alternative you can use this
syntax:

 [mysection]
 @,key = value, value2, value3

The leading '@,' means:

B<@>: This is a list

B<,>: ...and I'm using a ',' to delimit the values.

This might be weird to some people so if people who are only vaguely
familar with configuration files will be editing your data you might
want to either add a note about what the leading '@' sequence means or
just use the longer form.

=head1 TEMPLATES

=head2 General guidelines

=item *

All template files must have the *.tmpl suffix

=item *

Templates that are used for displaying data in a browser, should
strive to adhere to the following W3C recommondations: XHTML 1.0, CSS1
and CSS2, WAI WCAG 1.0, Conformance level 2 (AA). This is just being a
good web citizen.

=back

=head1 LOGGING

=head2 Meaning of logging levels

Our logging package (L<Log::Log4perl>) supports five levels. While
each level has a name to provide some guidance about how to use it
there are plenty of grey areas. Here are the levels and a few
pointers:

B<FATAL>

Situations where the system/application cannot continue safely and
must abort. Manual intervention is necessary to get things running
again.

Examples: database connection fails or cannot connect to other network
resource (LDAP)

B<ERROR>

Actual errors that need to be looked into. The application should be
able to continue running (albeit hobbled) despite having these errors
-- otherwise they'd be fatal -- but they're serious enough to look
into and diagnose later.

Note that by default messages logged at this level get stored
separately in the filesystem and displayed in the error browser.

Examples: cannot store session, missing configuration data that's
required for your application.

B<WARN>

Other problems you may encounter might not need to be later
investigated but are still important to note.

For situations that at some point later may lead to
errors.

Examples: cannot fetch or store data from a database but not due to
application validation errors (foreign key violations, constraint
violations); using default values in a configuration (e.g., the
default mail server is 'localhost' but that's probably wrong).

B<INFO>

Coarse status messages. This is useful to see what path a request
takes through an application but you don't necessarily want to see all
the data, or even all the individual subroutines called. 

Examples: entry points into main subroutines; certain types of
application-level errors: security violation, data constraint issues
(user enters incorrect data into a form).

B<DEBUG>

Detailed status messages. Turning this on means the user wants to see
everything.

=head2 An efficiency note

Leaving logging enabled can be an expensive proposition. But you can
make it much less expensive by putting a check on your logging
calls. So instead of:

 $log->debug( "Data structure so far: ", Data::Dumper::Dumper( \%big_hash ) );

you can use:

 $log->is_debug &&
     $log->debug( "Data structure so far: ", Data::Dumper::Dumper( \%big_hash ) );

and the expensive-to-generate string will never get generated unless
it has to.

=head1 COPYRIGHT

Copyright (c) 2005 Chris Winters. All rights reserved.

=head1 AUTHORS

Chris Winters E<lt>ch...@cw...E<gt>