NAME

CGI::Portable::AppSplitScreen - Delegate construction of a screen between several modules

DEPENDENCIES

Perl Version

        5.004

Standard Modules

        I<none>

Nonstandard Modules

        CGI::Portable 0.50
        CGI::Portable::AppStatic 0.50 (a superclass)

SYNOPSIS

Simple program whose output is made by combining several modules:

        #!/usr/bin/perl
        use strict;
        use warnings;

        require CGI::Portable;
        my $globals = CGI::Portable->new();

        use Cwd;
        $globals->file_path_root( cwd() );  # let us default to current working dir
        $globals->file_path_delimiter( $^O=~/Mac/i ? ":" : $^O=~/Win/i ? "\\" : "/" );

        require CGI::Portable::AdapterCGI;
        my $io = CGI::Portable::AdapterCGI->new();
        $io->fetch_user_input( $globals );

        $globals->default_application_title( 'Demo Application' );
        $globals->default_maintainer_name( 'Tony Simons' );
        $globals->default_maintainer_email_address( 'tony@aardvark.net' );

        $globals->current_user_path_level( 1 );
        $globals->set_prefs( 'myconfig.pl' );
        $globals->call_component( 'CGI::Portable::AppSplitScreen' );

        $io->send_user_output( $globals );

        1;

Content of file 'myconfig.pl' telling program what to do:

This is not a whole example, but you can get an idea what to substitute. This example shows 3 screen regions handled by 3 module instances, each of which has their own preferences and optional subdirectory for files.

        my $rh_preferences = { 
                delegate_list => [
                        {
                                file_subdir => 'menus',
                                preferences => { key => 'value' },
                                module_name => 'other::module::menu',
                                leave_scalars => 1,
                                replace_lists => 0,
                        },
                        {
                                file_subdir => 'forms',
                                preferences => { key1 => 'value', key2 => 'value' },
                                module_name => 'other::module::form',
                                leave_scalars => 0,
                                replace_lists => 0,
                        },
                        {
                                file_subdir => undef,
                                preferences => {},
                                module_name => 'other::module::disclaim',
                                leave_scalars => 1,
                                replace_lists => 0,
                        },
                ],
        };

DESCRIPTION

This Perl 5 object class is a simple encapsulated application, or "component", that runs in the CGI::Portable environment. It allows you to easily divide a response screen into multiple regions and then delegate the construction of each region to separate "components". You define the regions within the standard "preferences", and no other input is required. Specifically, you use the "delegate_list" array preference; each array element describes a region, and the created regions appear consecutively in the same order as in the array. Each element says what delegate module to call and what its preferences are. This class is subclassed from CGI::Portable::AppStatic, which is convenient if you want to do simple post-processing of your new screen using its preferences. This module is designed to be easily subclassed by your own application components, should you wish to extend or customize its functionality.

SYNTAX

This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $self->method().

This class does not have any of its own stored properties, so there is no risk of property namespace collisions with subclasses. Instead, you must provide the CGI::Portable object to each method explicitely as its first argument.

THE ONLY PUBLIC METHOD

main( GLOBALS )

You invoke this method to run the application component that is encapsulated by this class. The required argument GLOBALS is an CGI::Portable object that you have previously configured to hold the instance settings and user input for this class. When this method returns then the encapsulated application will have finished and you can get its user output from the CGI::Portable object.

PREFERENCES HANDLED BY THIS MODULE

This module is a subclass of CGI::Portable::AppStatic and will handle all of that module's preferences in addition to the new ones discussed below.

The only preference specifically for CGI::Portable::AppSplitScreen allows you to define a list of other modules which are all to be called in order to construct a portion of the result screen. AppSplitScreen doesn't normally do any screen construction by itself, but rather handles the logic required to call a list of modules and stitch together their results. The key preference that you need to set is "delegate_list". See the SYNOPSIS for the format of that preference.

delegate_list

This array-ref preference is a delegation list which divides the result screen into a list of consecutive regions, and matches each region with an "application component" module instance that will handle the content of that region. The array elements are hash-refs that say what other module to call and what its config preferences are. Any elements that are not hash-refs are ignored.

Each of these hash-refs must have values for at least these two keys set: "module_name" and "preferences". Each can optionally have these three keys set: "file_subdir", "leave_scalars", "replace_lists". The value for "module_name" is a scalar having the name of the Perl 5 module to invoke as an "application component" that will make the new result screen. The value for "preferences" can be either a hash-ref having literal preferences for the invoked module, or a scalar having a filename of a Perl file that can be executed to return the same preferences hash ref; it must be an empty hash ref if the module takes no preferences. The value for "file_subdir" is a relative file system path within which the invoked module should look for its files (or config file) if any; if this value is not set then the current file directory is used instead. The values for "leave_scalars" and "replace_lists" are used when stitching the delegates' output together, in order to better control when conflicting outputs have priority over each other (eg: there can be only one document title).

Delegated modules operate within a new "context" created by the current CGI::Portable object's make_new_context() method. Within that context, AppSplitScreen does the following: 1. call navigate_file_path() with the "file_subdir" value as its argument; 2. call set_prefs() with the "preferences" value as its argument; 3. call call_component() with the "module_name" value as its argument. Finally, the output held by the inner context is saved using the current CGI::Portable object's take_context_output() method, which takes the "leave_scalars" and "replace_lists" values as its last two optional arguments.

PRIVATE METHODS FOR USE BY SUBCLASSES

set_split_screen_attach_delegate_list( GLOBALS )

This method will iterate through all the elements of the "delegate_list" array preference and use each element to construct a consecutive screen region. For each element, the method set_split_screen_attach_delegate_list() is called to process it as a delegate. This method returns without doing anything if there is no "delegate_list" preference or it isn't an array.

set_split_screen_attach_one_delegate( GLOBALS, DELEGATE )

This method will use its DELEGATE argument to construct a new screen region and append it to any existing response in the GLOBALS context argument. DELEGATE is a hash ref whose values describe how the new screen region is to be made. It's properties are described by the delegate_list preference documentation, above, as DELEGATE can be set as an element in the delegate_list array. This method returns without doing anything if DELEGATE is not a valid hash ref.

AUTHOR

Copyright (c) 1999-2004, Darren R. Duncan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. However, I do request that this copyright information and credits remain attached to the file. If you modify this module and redistribute a changed version then please attach a note listing the modifications. This module is available "as-is" and the author can not be held accountable for any problems resulting from its use.

I am always interested in knowing how my work helps others, so if you put this module to use in any of your own products or services then I would appreciate (but not require) it if you send me the website url for said product or service, so I know who you are. Also, if you make non-proprietary changes to the module because it doesn't work the way you need, and you are willing to make these freely available, then please send me a copy so that I can roll desirable changes into the main release.

Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.

SEE ALSO

perl(1), CGI::Portable, CGI::Portable::AppStatic, CGI::Portable::AppMultiScreen.

cpanm CGI::Portable

perl -MCPAN -e shell
install CGI::Portable