OpenInteract2::Manual::API - API guidelines for OpenInteract2
This document will provide an overview of the different APIs in OpenInteract2 -- configuration, templating and interfaces, logging, coding, etc. -- and provide recommended uses.
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 (OpenInteract2::Config::Ini) but it's useful to put a few usage guidelines here.
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:
@: This is a list
,: ...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.
The Template Toolkit is a great piece of software and is quite well documented. But there's a lot of documentation so it might be confusing on a starting point. A good one is the Template::Manual::Intro document -- it gives you a good idea about using templates, templates as components, the different types of data you can pass into a template and more.
Some other good documents are: Template::Manual::Syntax and Template::Manual::Directives to give you an idea of how to 'speak' and your available vocabulary.
One more thing: you have a number of OI2-specific functions available in the OI2 plugin -- read OpenInteract2::TT2::Plugin for what you can do with lots of examples.
The Template Toolkit is very flexible about bringing in other templates. You can use either INCLUDE or PROCESS to bring in another template and evaluate it, and those templates can bring in other templates too, and so on down the line. If you're not careful you can get a fairly complicated sequence of includes that makes debugging difficult -- for example, the templates to create a SELECT form element include:
INCLUDE
PROCESS
form_select form_select_intro form_select_option form_select_options_iterator form_select_options_list form_select_options_plain_list
So a simple 'INCLUDE form_select' will bring in 'form_select_intro', and assuming you pass in an 'iterator' argument will call 'form_select_options_iterator' which will call 'form_select_option' multiple times to create the individual OPTION elements. Probably a little too complicated for a little-old dropdown box...
All template files must have the *.tmpl suffix
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.
Our logging package (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:
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)
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.
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).
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).
DEBUG
Detailed status messages. Turning this on means the user wants to see everything.
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.
Copyright (c) 2005 Chris Winters. All rights reserved.
Chris Winters <chris@cwinters.com>
To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenInteract2::URL
CPAN shell
perl -MCPAN -e shell install OpenInteract2::URL
For more information on module installation, please visit the detailed CPAN module installation guide.