/ 
OpenInteract-1.99_06
River stage zero No dependents
/ OpenInteract2::Manual::API

NAME

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

SYNOPSIS

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

CONFIGURATION

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 (OpenInteract2::Config::Ini) but it's useful to put a few usage guidelines here.

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:

@: 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.

TEMPLATES: TEMPLATE TOOLKIT

Pointers

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.

Including other templates

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:

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...

General guidelines

  • 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.

LOGGING

Meaning of logging levels

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.

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.

COPYRIGHT

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

AUTHORS

Chris Winters <chris@cwinters.com>