NAME

Form::Sensible::DelegateConnection - Represents a connection between one object and another

SYNOPSIS

 sub the_options {
    my $calling_object = shift;
    
    # do stuff to get options and return them
 }
 
 ## calls the_options when the delegate is invoked
 my $options_delegate = FSConnector( \&the_options );
 
 ## OR --
 
 my $options_delegate = FSConnector( sub { 
                                            my $calling_object = shift;
                                            
                                            ## do stuff to get options and return them
                                         } );
 
 
 ## OR --
 
 my $data_source_object = Data::Source->new(...);
 
 
 ## calls $data_source_object->get_option_data($calling_object, ...); when the delegate is invoked
 ## Automatically captures your $data_source_object in a closure.
 
 my $options_delegate = FSConnector( $data_source_object, "get_option_data");
 
 ## OR --
 
 my $options_delegate = Form::Sensible::DelegateConnection->new( delegate_function => \&the_options );

DESCRIPTION

Form::Sensible::DelegateConnection is an object that represents a connection between one object and another. In Form::Sensible when an object can have its behavior customized by another object, a Delegate, a "DelegateConnection" object is usually used to create the link between the two objects. See Form::Sensible::Delegation for more information on how DelegateConnection objects are used within Form::Sensible.

ATTRIBUTES

"delegate_function($calling_object, $optional_additional_arguments, ... )": The "delegate_function" refers to a function that will be run when this delegate connection is used. In most cases you will not access this attribute directly, preferring the FSConnector() method, though if you are into deep voodoo, you may.

METHODS

new( %options )

Creates a new DelegateConnection object with the provided options. All the attributes above may be passed.

"call( $calling_object, @argument_list )"

Calls the delegate function for the $calling_object using the @argument_list. This is essentially a wrapper to overload an object so that if it is accessed directly as a code ref, it will call the delegate function:

    my $options_delegate = Form::Sensible::DelegateConnection->new( delegate_function => \&the_options );
    $options_delegate->( ... ); # same as $options_delegate->delegate_function->( ... )

FUNCTIONS

FSConnector(...)

The "FSConnector" function is available if you have "use"d either "Form::Sensible" or "Form::Sensible::DelegateConnection". It is used to easily create a "Form::Sensible::DelegateConnection" object in-place. You can call it two ways, first, passing a code ref:

 # instead of:
 my $connection = Form::Sensible::DelegateConnection->new( delegate_function => sub { ... } );
 
 # this does the same thing:
 
 my $connection = FSConnector( sub { ... } );

This is a modest savings in typing, but can be very convenient when you are defining a number of delegates during form creation, for example.

FSConnector( ... ) is particularly useful when linking a delegate connection to a method on an object. This method looks like this:

 my $connection = FSConnector( $object, 'method_to_call');

When used this way, The "FSConnector" function will create a code ref for you automatically capturing the passed object in a closure. Again, you can do this yourself, but this makes your setup code a lot clearer.

As a further benefit, both methods will take additional args which will be passed to the function or method after the args passed by the calling object:

 my $connection = FSConnector( $object, 'method_to_call', 'additional','args');

This can be useful, for example, when you are using the same object / method repeatedly, but need slightly different information in each case.

AUTHOR

Jay Kuri - <jayk@cpan.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.