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.
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
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:
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...
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:
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)
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.
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).
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).
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 <email@example.com>