view release on metacpan or  search on metacpan

lib/Apache2/Translation/_base.pod  view on Meta::CPAN

=head1 NAME

Apache2::Translation::_base - The Apache2::Translation provider interface

=head1 DESCRIPTION

A translation provider must implement the following interface. It is free to
support more functions.

=head2 B<Methods>

=over 4

=item B<new( NAME=E<gt>VALUE, ... )>

the constructor. It is called once from the master Apache during its
configuration.

=item B<child_init>

This method is optional. If defined it is called from a
C<PerlChildInitHandler> and can be used to do some initializations.
The C<DB> provider connects here to the database and decides to use
a singleton or not.

=item B<start>

This method is called at start of each uri translation. The DB provider
checks the cache here.

=item B<stop>

is called after each uri translation.

=item B<fetch( $key, $uri, $with_notes )>

is called to fetch a list of blocks. The result is a list of arrays:

 ([block, order, action],
  [block, order, action],
  ...)

If the adminstration WEB interface is to be used C<fetch> must return a
list of:

 ([block, order, action, id],
  [block, order, action, id],
  ...)

where C<id> is a unique key.

If the C<$with_notes> parameter is true C<fetch> is called from the
admin interface and wants to fetch also notes. In this case the return
value is a list like this:

 ([block, order, action, id, note],
  [block, order, action, id, note],
  ...)

Notes are comments on actions for the user of the admin interface. They are
not evaluated otherwize.

=back

The following interface is optional. It has to be implemented if the provider
is to be used also with the administration WEB interface.

=over 4

=item B<can_notes>

returns true if a provider supports notes in its current configuration.

=item B<list_keys>

returns a sorted list of known keys.

=item B<list_keys_and_uris( $key )>

C<$key> is a string.

The function returns a sorted list of C<[KEY, URI]> pairs. If C<$key> is empty
all pairs are returned. Otherwise only pairs where C<$key eq KEY> are