[Catalyst-dev] RFC: Catalyst::View::Download

[Travis Chase]

A refined focus of what Catalyst::View::CSV was to be apart of. Note:
Catalyst::View::CSV will move forward, it is instead a part of this package
as Catalyst::View::Download::CSV. Also note, I intend to add more
downloadable formats besides the simple ones (CSV, Plain) I have listed.

- Travis

=3Dhead1 NAME

Catalyst::View::Download

=3Dhead1 VERSION

Version 0.01

=3Dhead1 SYNOPSIS

    # lib/MyApp/View/Download.pm
    package MyApp::View::Download;
    use base qw( Catalyst::View::Download );
    1;

    # lib/MyApp/Controller/SomeController.pm
    sub example_action_1 : Local {
        my ($self, $c) =3D @_;

        my $content_type =3D $c->request->params->{'content_type'} || 'plai=
n';
# 'plain' or 'csv'

        $c->header('Content-Type' =3D> 'text/'.$content_type); # Set the
content type so Catalyst::View::Download can determine how to process it.

        # Array reference of array references.
        my $data =3D [
            ['col 1','col 2','col ...','col N'], # row 1
            ['col 1','col 2','col ...','col N'], # row 2
            ['col 1','col 2','col ...','col N'], # row ...
            ['col 1','col 2','col ...','col N']  # row N
        ];

        # If the chosen content_type is 'csv' then the render function of
Catalyst::View::Download::CSV will be called which uses the 'csv' stash key
        $c->stash->{'csv'} =3D $data;

        # For plain text in this example we just dump the example array
        # Catalyst::View::Download::Plain will use either the 'plain' stash
key or just pull from $c->response->body
        use Data::Dumper;
        $c->response->body( Dumper( $data ) )

        # Finally forward processing to the Download View
        $c->forward('MyApp::View::Download');
    }

=3Dhead1 SUBROUTINES

=3Dhead2 process

This method will be called by Catalyst if it is asked to forward to a
component without a specified action.

=3Dhead2 render

Allows others to use this view for much more fine-grained content
generation.

=3Dhead1 CONFIG

=3Dover 4

=3Ditem default

Determines which Content-Type to use by default. Default: 'text/plain'

    $c->view('MyApp::View::Download')->config('default' =3D> 'text/plain');

=3Ditem content_type

A hash ref of hash refs. Each key in content_type is Content-Type that is
handled by this view.

    $c->view('MyApp::View::Download')->config->{'content_type'}{'text/csv'}
=3D {
        'outfile' =3D> 'somefile.csv',
        'module' =3D> 'My::Module'
    };

The Content-Type key refers to it's own hash of parameters to determine the
actions thie view should take for that Content-Type.

'outfile' - The name and extenstion of the file that will display by default
in the download dialog box.

'module' - The name of the module that will handle data output. If there is
a plus symbol '+' at the beginning of the module name, this will indicate
that the module is a Catalyst::View module will will add 'Catalyst::View::'
to the beginning of the module name.


$c->view('MyApp::View::Download')->config->{'content_type'}{'text/csv'}{'mo=
dule'}
=3D '+Download::CSV'; # Module Loaded: Catalyst::View::Download::CSV


$c->view('MyApp::View::Download')->config->{'content_type'}{'text/csv'}{'mo=
dule'}
=3D 'My::Module::CSV'; # Module Loaded: My::Module::CSV

=3Dback

=3Dhead1 Content-Type Module Requirements

Any module set as 'the' module for a certain Content-Type needs to have a
subroutine named 'render' that returns the content to output with the
following parameters handled.

=3Dover 4

=3Ditem $c

The catalyst $c variable

=3Ditem $template

In case a template file is needed for the module. This view will pass
$c->stash->{template} as this value.

=3Ditem $args

A list of arguments the module will use to process the data into content.
This view will pass $c->stash as this value.

=3Dback

=3Dhead1 CURRENT CONTENT-TYPES SUPPORTED

=3Dhead2 text/csv

Catalyst::View::Download has the following default configuration for this
Content-Type

    $c->view('MyApp::View::Download')->config->{'content_type'}{'text/csv'}
=3D {
        'outfile' =3D> 'data.csv',
        'module' =3D> '+Download::CSV'
    };

See L<Catalyst::View::Download::CSV> for more details.

=3Dhead2 text/plain

Catalyst::View::Download has the following default configuration for this
Content-Type

    $c->view('MyApp::View::Download')->config->{'default'} =3D 'text/plain';

    $c->view('MyApp::View::Download')->config->{'content_type'}{'text/csv'}
=3D {
        'outfile' =3D> 'data.csv',
        'module' =3D> '+Download::CSV'
    };

See L<Catalyst::View::Download::Plain> for more details.

=3Dhead1 AUTHOR

Travis Chase, C<< <gaudeon at cpan.org> >>

=3Dhead1 BUGS

Please report any bugs or feature requests to C<bug-catalyst-view-download
at rt.cpan.org>, or through
the web interface at L<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=3DCatalyst-View-Download>.  I
will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=3Dhead1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Catalyst::View::Download

You can also look for information at:

=3Dover 4

=3Ditem * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=3DCatalyst-View-Download>

=3Ditem * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Catalyst-View-Download>

=3Ditem * CPAN Ratings

L<http://cpanratings.perl.org/d/Catalyst-View-Download>

=3Ditem * Search CPAN

L<http://search.cpan.org/dist/Catalyst-View-Download>

=3Dback

=3Dhead1 SEE ALSO

L<Catalyst> L<Catalyst::View>

=3Dhead1 CONTRIBUTORS

=3Dhead1 ACKNOWLEDGEMENTS

Thanks to following people for their constructive comments and help:

=3Dover 4

=3Ditem J. Shirley

=3Ditem Jonathan Rockway

=3Dback

Thanks also to my company Ti4 Technologies for their financial support. L<
http://www.ti4tech.com/>

=3Dhead1 COPYRIGHT & LICENSE

Copyright 2008 Travis Chase, all rights reserved.

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

=3Dcut
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst-dev/attachments/20080305/f=
b129e14/attachment.htm