/ 
HTML-DragAndDrop-0.01
River stage zero No dependents
/ HTML::DragAndDrop

NAME

HTML::DragAndDrop - Provides a perl interface for easy use of Walter Zorn's dragdrop Javascript library. See http://www.walterzorn.com/dragdrop/dragdrop_e.htm.

SYNOPSIS

use HTML::DragAndDrop;

my $dd = HTML::DragAndDrop->new(
    javascript_dir => '/javascript/',
);

$dd->add_dragable(
    name => 'dragable1',
    src => '/images/www3.png',
    width => 64, height => 64,
);

print $dd->output_html;
print $dd->output_script;

DESCRIPTION

The HTML::DragAndDrop module provides a Perl interface to Walter Zorn's Javascript Drag and Drop library. See http://www.walterzorn.com/dragdrop/dragdrop_e.htm.

Walter's Javascript library provides:

A Cross-browser JavaScript DHTML Library which adds Drag Drop 
functionality to layers and to any desired image, even those 
integrated into the text flow.

METHODS

new

my $dd = CGI::DragDrop->new(
    javascript_dir => '/javascript/',
);

Create a new DragDrop object. The various options are described below:

javascript_dir

Defaults to /. This is the url path to the directory containing wz_dragdrop.js. It can be relative or absolute.

add_dragable

$dd->add_dragable(
    name => 'drag1',
    width => 120, height => 120,
    left => 10, top => 60,
    content => $html_to_display,
    # or
    # src => $image_url,
    class => $css_class,
    features => $features,
);

This function defines the div tag or image tag that will be dragable. The dragable item must have a name. If your dragable object is an image, then it must also have a width and a height.

name

The name is the HTML id attribute if the dragable object is not an image, otherwise it is the HTML name attribute. It is output in the html tag, and is compulsary for a dragable object.

width

The width (and height) attribute is compulsory for images. It works just like defining the width in the HTML or stylesheet. You must use an absolute value for the width (e.g. 240px) and not a relative value (33%).

height

The height (and width) attribute is compulsory for images. It works just like defining the height in the HTML or stylesheet. You must use an absolute value for the height (e.g. 240px) and not a relative value (33%).

left

Defines how far from the left of edge of the containing object the dragable object will be when the page loads. The containing object is usually the browser window, but could be another html tag, for example a div tag. For those who are stylesheet savvy, this is the left absolute positioning style.

top

Defines how far from the top of edge of the containing object the dragable object will be when the page loads. The containing object is usually the browser window, but could be another html tag, for example a div tag. For those who are stylesheet savvy, this is the top absolute positioning style.

content

If content is provided, the module will create a div tag with an id of the name provided, that contains the content. The content can be straight text or html. If both content and src (image) attributes are present, the src will be used.

src

The source is the url of an image to use. The module generates an IMG tag with a name of the name provided.

class

If a class is specified the dragable object will be created with the class given, otherwise it will have a class of "dragable". This is for use with stylesheets, and is especially handy when using the content attribute.

features

For a complete understanding of the features available, see Walter Zorn's site. The features are passed directly in to the javascript library functions. If you want to use more than one feature, join them in a string with '+' characters. For example: 'RESIZABLE+VERTICAL+CURSOR_HAND', will give you a resizable object, that only moves along the vertical axis, and the mouse cursor displays a hand when hovering over the object. A basic description of the features available is below:

feature            applies to    description
--------           -----------   ------------
CLONE              images        Makes a single, dragable clone
COPY               images        Makes x dragable copies, e.g. COPY+5
CURSOR_DEFAULT     all           Default cursor onmouseover
CURSOR_CROSSHAIR   all	     Crosshair cursor onmouseover
CURSOR_HAND        all           Hand cursor onmouseover
CURSOR_MOVE        all           Move cursor onmouseover
CURSOR_E_RESIZE    all           East resize cursor onmouseover
CURSOR_NE_RESIZE   all           NorthEast resize cursor onmouseover
CURSOR_NW_RESIZE   all           NorthWest resize cursor onmouseover
CURSOR_N_RESIZE    all           North resize cursor onmouseover
CURSOR_SE_RESIZE   all           SouthEast resize cursor onmouseover
CURSOR_SW_RESIZE   all           SouthWest resize cursor onmouseover
CURSOR_W_RESIZE    all           West resize cursor onmouseover
CURSOR_TEXT        all           Text cursor onmouseover
CURSOR_WAIT        all           Wait cursor onmouseover
CURSOR_HELP        all           Help cursor onmouseover
DETACH_CHILDREN    layers        Dragable objects inside the div 
                                 don't move with it
HORIZONTAL         all           Only move on the horizontal axis
MAXWIDTH           all           Maximum width to resize to
MAXHEIGHT          all           Maximum height to resize to
MINWIDTH           all           Minimum width to resize to
MINHEIGHT          all           Minimum height to resize to
MAXOFFBOTTOM       all           Maximum downwards movement
MAXOFFLEFT         all           Maximum left movement
MAXOFFRIGHT        all           Maximum right movement
MAXOFFTOP          all           Maximum upwards movement
NO_ALT             images        De-activates the ALT and TITLE attributes
NO_DRAG            all           Object is not dragable
RESET_Z            all           Restores the object's z-index once dropped
RESIZABLE          all           Object can be resized
SCALABLE           all           Object maintains width/height ratio 
                                 when resized
SCROLL             all           Browser window will scroll as objects 
                                 are dragged to the edge
VERTICAL           all           Only move on the vertical axis

output_html

The output_html method returns all the html to generate the dragable objects. The output MUST be printed before the output of the output_script method.

output_script

The output_script method returns the javascript needed to make the objects dragable (or have whatever other features you have given them), in a script block. The output of this method MUST be printed after the output of the output_html method.

SEE ALSO

See Walter Zorn's website http://www.walterzorn.com.

And the examples below

EXAMPLES

Example One - An Image

This example shows an image that can be dragged around the browser window.

To run this example, you will need the image script.png in a web-accessible directory called images. (e.g. you should be able to access it as /images/script.png). You will also need Walter Zorn's wz_dragdrop.js in a web-accessible directory called javascript.

#!/usr/bin/perl
use strict;
use warnings;
use CGI;
use HTML::DragAndDrop;

my $q = new CGI;
my $dd = HTML::DragAndDrop->new(
    javascript_dir => '/javascript/',
);

$dd->add_dragable(
    name => 'dragable1',
    src => '/images/script.png',
    width => 64, height => 64,
);

print $q->header, $q->start_html;
print $dd->output_html;
print $dd->output_script;
print $q->end_html;

Example Two - Some div tags

This example shows two div tags. On that can be dragged around the browser window and another than can only be dragged a limited distance in the horizontal plane but cannot be dragged vertically.

To run this example you will need Walter Zorn's wz_dragdrop.js in a web-accessible directory called javascript.

#!/usr/bin/perl
use strict;
use warnings;
use CGI;
use CGI::Carp qw(fatalsToBrowser);
use HTML::DragAndDrop;

my $q = new CGI;
my $dd = HTML::DragAndDrop->new(
    javascript_dir => '/javascript/',
);

print $q->header;
print $q->start_html(
    -title => 'D+D',
    -style => {code => '
        .dragable {
            border: 3pt ridge lightsteelblue;
            font-family: verdana, arial, sans-serif;
            color: #006;
            background: #EEEEEE;
            padding: 1em;
            font-weight: bold;
        }
    '}
);

$dd->add_dragable(
    name => 'drag1',
    width => '120px', height => '120px',
    left => '200px', top => '60px',
    content => 'Constrained horzontal movement only',
    features => 'CURSOR_HAND+HORIZONTAL+MAXOFFLEFT+200+MAXOFFRIGHT+200',
);

$dd->add_dragable(
    name => 'drag2',
    width => '120px', height => '120px',
    left => '300px', top => '200px',
    content => 'Any movement allowed',
    features => 'CURSOR_HAND',
);

print $dd->output_html;
print $dd->output_script;
print $q->end_html;

AUTHOR

Becky Alcorn, <becky@unisolve.com.au> Simon Taylor, <simon@unisolve.com.au> Unisolve Pty Ltd

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Unisolve Pty Ltd

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 183:

You forgot a '=back' before '=head1'

Around line 191:

'=item' outside of any '=over'

Around line 196:

You forgot a '=back' before '=head2'

Around line 316:

You forgot a '=back' before '=head2'