NAME

OpenInteract2::Filter - Initialize and manage content filters

SYNOPSIS

 # Declare a filter 'allcaps' in $WEBSITE_DIR/conf/filter.ini
 
 [filters allcaps]
 class = OpenInteract2::Filter::AllCaps
 
 # You can also declare it in your package's package.conf file
 
 name           mypackage
 version        2.00
 author         Kilroy (kilroy@washere.com)
 filter         allcaps   OpenInteract2::Filter::AllCaps
 
 # Associate the filter with an action
 
 [filter_action]
 news = allcaps
 
 # Create the filter
 
 package OpenInteract2::Filter::AllCaps;
 
 use strict;
 
 sub update {
     my ( $class, $action, $type, $content ) = @_;
     return unless ( $type eq 'filter' );
     $$content =~ s/^(.*)$/\U$1\E/;
 }
 
 # Programmatically add a new filter
 
 CTX->add_filter( 'foobar', { class => 'OpenInteract2::Filter::Foobar' } );

DESCRIPTION

This class provides methods for initializing filters and attaching them to action objects or action classes.

METHODS

All methods are class methods (for now). Note that when we discuss a 'filter' it could mean a class name, instantiated object or subroutine reference. (A filter is just an observer, see Class::Observable for what constitutes an observer.)

create_filter_filename()

Returns the full path to the server filter file, normally $WEBSITE_DIR/conf/filter.ini.

add_filter_to_action( $filter_name, $action | $action_name )

Registers the filter referenced by $filter_name to the action $action or the action class referenced by $action_name. If you pass in $action the filter will go away when the object is disposed at the end of the request; with $action_name the filter will persist until the server is shutdown.

Returns: assigned filter

register_filter( $filter_name, \%filter_info, \%filter_registry )

Creates a filter with the name $filter_name and saves the information in \%filter_registry. If the filter cannot be created (due to a library not being available or an object not being instantiable) an error is logged but no exception thrown.

Returns: created filter, undef if an error encountered

initialize()

Reads filters declared in packages and in the server's filter.ini file, brings in the libraries referenced by the filters, creates a filter name-to-filter registry and saves it to the context.

Note that filters declared at the server will override filters declared in a package if they share the same name.

You'd almost certainly never need to call this as it's called from OpenInteract2::Setup.

Returns: nothing

COPYRIGHT

Copyright (c) 2002-2004 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>