.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Application::Plugin::AJAXUpload 3pm"
.TH CGI::Application::Plugin::AJAXUpload 3pm "2011-12-05" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Application::Plugin::AJAXUpload \- Run mode to handle a file upload and return a JSON response
.SH "VERSION"
.IX Header "VERSION"
This document describes CGI::Application::Plugin::AJAXUpload version 0.0.3
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use MyWebApp;
\&    use CGI::Application::Plugin::JSON qw(to_json);
\&    use CGI::Application::Plugin::AJAXUpload;
\&
\&    sub setup {
\&        my $c = shift;
\&        $c\->ajax_upload_httpdocs(\*(Aq/var/www/vhosts/mywebapp/httpdocs\*(Aq);
\&
\&        $c\->ajax_upload_setup(
\&            run_mode=>\*(Aqfile_upload\*(Aq,
\&            upload_subdir=>\*(Aq/img/uploads\*(Aq,
\&        );
\&        return;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a customisable run mode that handles a file upload
and responds with a \s-1JSON\s0 message like the following:
.PP
.Vb 1
\&    {status: \*(AqUPLOADED\*(Aq, image_url: \*(Aq/img/uploads/666.png\*(Aq}
.Ve
.PP
or on failure
.PP
.Vb 1
\&    {status: \*(AqThe image was too big.\*(Aq}
.Ve
.PP
This is specifically intended to provide a CGI::Application based back
end for AllMyBrain.com <http://allmybrain.com>'s 
image upload extension <http://allmybrain.com/2007/10/16/an-image-upload-extension-for-yui-rich-text-editor> to the
\&\s-1YUI\s0 rich text editor <http://developer.yahoo.com/yui/editor>. However as far as
I can see it could be used as a back end for any CGI::Application website that uploads files behind the scenes using \s-1AJAX\s0. In any case this module does \s-1NOT\s0
provide any of that client side code and you must also map the run mode onto the \s-1URL\s0 used by client-side code.
That said a working example is provided which could form the basis of
a rich text editor.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "ajax_upload_httpdocs"
.IX Subsection "ajax_upload_httpdocs"
The module needs to know the document root because it will need to
to copy the file to a sub-directory of the document root,
and it will need to pass that sub-directory back to the client as part
of the \s-1URL\s0. If passed a value it will store that as the document root.
If not passed a value it will return the document root.
.SS "ajax_upload_setup"
.IX Subsection "ajax_upload_setup"
This method sets up a run mode to handle a file upload
and return a \s-1JSON\s0 message providing status. It takes a number of named
parameters:
.IP "upload_subdir" 4
.IX Item "upload_subdir"
This is the sub-directory of \fIhttpdocs_dir\fR where the files will actually
be written to. It must be writable. It defaults to '/img/uploads'.
.IP "dfv_profile" 4
.IX Item "dfv_profile"
This is a Data::FormValidator profile. The hash array that is validated
consists of the fields described below. A very basic profile is provided by
default.
.RS 4
.IP "\fIvalue\fR This is contains the actual data contained in the upload. It will be untainted. One can of course apply filters that resize the image (assuming it is an image) or scrub the \s-1HTML\s0 (if that is appropriate)." 4
.IX Item "value This is contains the actual data contained in the upload. It will be untainted. One can of course apply filters that resize the image (assuming it is an image) or scrub the HTML (if that is appropriate)."
.PD 0
.IP "\fIfile_name\fR This is the filename given by the browser. By default it will be required to be no more than 30 alphanumeric, hyphen or full stop, underscore characters; it will be untainted and passed through unmodified. One could however specify a filter that completely ignores the filename, generates a safe one and does other housekeeping." 4
.IX Item "file_name This is the filename given by the browser. By default it will be required to be no more than 30 alphanumeric, hyphen or full stop, underscore characters; it will be untainted and passed through unmodified. One could however specify a filter that completely ignores the filename, generates a safe one and does other housekeeping."
.IP "\fImime_type\fR This is the file extension passed by the browser." 4
.IX Item "mime_type This is the file extension passed by the browser."
.IP "\fIdata_size\fR By default this is required to be less than 512K." 4
.IX Item "data_size By default this is required to be less than 512K."
.RE
.RS 4
.PD
.Sp
Note that this module's handling of file upload and data validation is
somewhat different from that expected by
Data::FormValidator::Constraints::Upload and 
Data::FormValidator::Filters::Image. Those modules work with file handles.
The Data::FormValidator profiles required  by this module are expected
to work with the data and meta data.
.RE
.IP "run_mode" 4
.IX Item "run_mode"
This is the name of the run mode that will handle this upload. It defaults to
\&\fIajax_upload_rm\fR.
.SS "ajax_upload_default_profile"
.IX Subsection "ajax_upload_default_profile"
This returns a hash reference to the default Data::FormValidator
profile. It can be called as a class method.
.SS "_ajax_upload_rm"
.IX Subsection "_ajax_upload_rm"
This private method forms the implementation of the run mode. It requires a
\&\fIfile\fR \s-1CGI\s0 query parameter that provides the file data. Optionally it also
takes a \fIvalidate\fR parameter that will make other more paranoid checks.
These checks are only optional because if the system is set up correctly
they should never fail.
.PP
It takes the following actions:
.IP "\-\-" 4
It will get the filename and data associated with the upload and 
pass the data through the Data::FormValidator if a profile is 
supplied.
.IP "\-\-" 4
If it fails the Data::FormValidator test a failed message will be passed
back to the caller.
.IP "\-\-" 4
If the \fIvalidate\fR parameter is set the setup will check. If there
is a problem a status message will be passed back to the user.
.IP "\-\-" 4
The data will then be copied to the given file, its path being the 
combination of the \fIhttpdocs_dir\fR parameter, the
\&\fIupload_subdir\fR and the generated file name.
.IP "\-" 4
The successful \s-1JSON\s0 message will be passed back to the client.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Most error messages will be passed back to the client as a \s-1JSON\s0
message, though in a sanitised form. One error 'Internal Error' is
fairly generic and so the underlying error message is written to standard 
error.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
CGI::Application::Plugin::AJAXUpload requires no configuration files or
environment variables. However the client side code, the \s-1URL\s0 to run mode
dispatching and the general web server setup is not supplied.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
This is using the \f(CW\*(C`to_json\*(C'\fR method from CGI::Application::Plugin::JSON.
As such that module needs to be exported before this module. Or of course you
could just define your own.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-cgi\-application\-plugin\-ajaxupload@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>.
.PP
One really odd thing is that the content header of the \s-1AJAX\s0 reply cannot
be 'application/json' as one would expect. This module sets it to
\&'text/javascript' which works. There is a very short discussion on the
\&\s-1YUI\s0 forum <http://yuilibrary.com/forum/viewtopic.php?f=89&t=4743&p=16459&hilit=POST+connection#p16459>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Nicholas Bamber  \f(CW\*(C`<nicholas@periapt.co.uk>\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2010, Nicholas Bamber \f(CW\*(C`<nicholas@periapt.co.uk>\*(C'\fR. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.PP
The javascript code in the example draws heavily on the code provided
by AllMyBrain.com.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.