NAME
    Dancer::Plugin::Dropbox - Dancer plugin for a dropbox-like applications.

VERSION
    Version 0.00001

    This release appears to work, but it is in an early stage of development
    and testing. You have been warned.

SYNOPSIS
    In the config:

      plugins:
        Dropbox:
          basedir: 'dropbox-data'
          template: 'dropbox-listing'
          token: index
          autocreate_root: 1
  
    In your route:

      get '/dropbox/*/' => sub {
          my ($user) = splat;
          return dropbox_send_file($user, "/");
      };
  
      get '/dropbox/*/**' => sub {
          my ($user, $filepath) = splat;
          return dropbox_send_file($user, $filepath);
      };
  
      post '/dropbox/*/**' => \&manage_uploads;
      post '/dropbox/*/' => \&manage_uploads;
  
      sub manage_uploads {
          my ($user, $filepath) = splat;
          if (my $uploaded = upload('upload_file')) {
              warning dropbox_upload_file($user, $filepath, $uploaded);
          
          }
          elsif (my $dirname = param("newdirname")) {
              dropbox_create_directory($user, $filepath, $dirname);
          }
          elsif (my $deletion = param("filedelete")) {
              dropbox_delete_file($user, $filepath, $deletion);
          }
          return redirect request->path;
      }
  
  Configuration
    The configuration keys are as follows:

    basedir
        The directory which will be the root of the dropbox users. The
        directory must already exist. Defaults to "dropbox-datadir" in the
        application directory.

    template
        The template to use. If not present, a minimal embedded template
        will be used.

    layout
        The layout to use (defaults to `main').

    token
        The token of your template to use (defaults to `listing') for the
        directory listing.

    autocreate_root
        If set to a true value, the root for the each user will be created
        on the first "GET" request, e.g. `dropbox-data/marco@test.tld/'

        Please note that the dropbox file will be left in a subdirectory of
        the basedir named with the username, so if you permit usernames with
        "/" or "\" or ".." inside the name, the user will never reach its
        files, effectively cutting it out.

  Exported keywords
    dropbox_send_file ($user, $filepath, \%template_tokens, \%listing_params)
    This keyword accepts a list of positional arguments or a single hash
    reference. If the given filename exists, it sends it to the client. If
    it's a directory, a directory listing is returned.

    The first argument is the dropbox user, which is also the subdirectory
    of the dropbox directory.

    The second argument is the path of the file, as a single string or as a
    arrayref, the same you could get from a Dancer's megasplat (`**'). If
    not provided, it will return the root of the user.

    The third argument is an hashref with the template tokens for the
    directory listing. This will be used only if the path points to a
    directory and ignored otherwise. The configuration file should specify
    at least the template to use.

      plugins:
        Dropbox:
          basedir: 'dropbox-data'
          template: 'dropbox-listing'
          token: index
  
    The fourth argument is an hashref for the autoindex function. See
    Dancer::Plugin::AutoIndex for details.

    The directory listing will set the template token specified in the
    configuration file under `token'.

    The alternate syntax using a hashref is the following:

      dropbox_send_file {
                         user => $username,
                         filepath => $filepath,
                         template_tokens => \%template_tokens,
                         listing_params  => \%listing_params,
                        };

    dropbox_upload_file($user, $filepath, $fileuploaded)
    This keyword manage the uploading of a file.

    The first argument is the dropbox user, used as root directory.

    The second argument is the desired path, a directory which must exists.

    The third argument is the Dancer::Request::Upload object which you can
    get with `upload("param_name")'.

    It returns true in case of success, false otherwise.

    dropbox_create_directory($user, $filepath, $dirname);
    The keyword creates a new directory on the top of an existing dropbox
    directory.

    The first argument is the user the directory belongs to in the dropbox
    application.

    The second argument is the path where the directory should be created.
    This is usually retrieved from the route against which the user posts
    the request. The directory must already exist.

    The third argument is the desired new name. It should constitute a
    single directory, so no directory separator is allowed.

    It returns true on success, false otherwise.

    dropbox_delete_file($user, $filepath, $filename);
    The keyword deletes a file or an empty directory belonging to an
    existing dropbox directory.

    The first argument is the dropbox user.

    The second argument is the parent directory of the target file. This is
    usually retrieved from the route against which the user posts the
    request.

    The third argument is the target to delete. No directory separator is
    allowed here.

    It returns true on success, false otherwise.

    Internally, it uses `unlink' on files and `rmdir' on directories.

AUTHOR
    Marco Pessotto, `<melmothx at gmail.com>'

BUGS
    Please report any bugs or feature requests to `bug-dancer-plugin-dropbox
    at rt.cpan.org', or through the web interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer-Plugin-Dropbox. I
    will be notified, and then you'll automatically be notified of progress
    on your bug as I make changes.

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

        perldoc Dancer::Plugin::Dropbox

    You can also look for information at:

    * RT: CPAN's request tracker (report bugs here)
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer-Plugin-Dropbox

    * AnnoCPAN: Annotated CPAN documentation
        http://annocpan.org/dist/Dancer-Plugin-Dropbox

    * CPAN Ratings
        http://cpanratings.perl.org/d/Dancer-Plugin-Dropbox

    * Search CPAN
        http://search.cpan.org/dist/Dancer-Plugin-Dropbox/

ACKNOWLEDGEMENTS
    Thanks to Stefan Hornburg (Racke) `racke@linuxia.de' for the initial
    code, ideas and support.

LICENSE AND COPYRIGHT
    Copyright 2013 Marco Pessotto.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the the Artistic License (2.0). You may obtain a copy
    of the full license at:

    http://www.perlfoundation.org/artistic_license_2_0

    Any use, modification, and distribution of the Standard or Modified
    Versions is governed by this Artistic License. By using, modifying or
    distributing the Package, you accept this license. Do not use, modify,
    or distribute the Package, if you do not accept this license.

    If your Modified Version has been derived from a Modified Version made
    by someone other than you, you are nevertheless required to ensure that
    your Modified Version complies with the requirements of this license.

    This license does not grant you the right to use any trademark, service
    mark, tradename, or logo of the Copyright Holder.

    This license includes the non-exclusive, worldwide, free-of-charge
    patent license to make, have made, use, offer to sell, sell, import and
    otherwise transfer the Package with respect to any patent claims
    licensable by the Copyright Holder that are necessarily infringed by the
    Package. If you institute patent litigation (including a cross-claim or
    counterclaim) against any party alleging that the Package constitutes
    direct or contributory patent infringement, then this Artistic License
    to you shall terminate on the date that such litigation is filed.

    Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
    AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
    THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
    PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
    YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
    CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

