/ 
JavaScript-Framework-jQuery-0.07
River stage one • 1 direct dependent • 1 total dependent
/ JavaScript::Framework::jQuery

NAME

JavaScript::Framework::jQuery - Generate markup and code for jQuery JavaScript framework

VERSION

Version 0.01

SYNOPSIS

use JavaScript::Framework::jQuery;

my $jquery = JavaScript::Framework::jQuery->new(
   library => {
       src => [ '/static/js/jquery.min.js' ],
       css => [
           { href => 'theme/ui.all.css', media => 'screen' },
       ],
   },
   plugins => [
        {
            name => mcDropdown,
            library => {
                src => [
                    '/js/jquery.mcdropdown.js',
                    '/js/jquery.bgiframe.js',
                ],
                css => [
                    { href => '/css/jquery.mcdropdown.css', media => 'all' },
                ],
            },
        },
   ],
);

# alternative to configuring the plugin's asset locations in the
# constructor parameters:

$jquery->config_plugin(
   name => 'mcDropdown',
   library => {
       src => [
           '/js/jquery.mcdropdown.js',
           '/js/jquery.bgiframe.js',
       ],
       css => [
           { href => '/css/jquery.mcdropdown.css', media => 'all' },
       ],
   },
);

# add JavaScript constructor for the plugin

$jquery->construct_plugin(
   name => 'mcDropdown',
   target_selector => '#category',
   srl_ul => '#categorymenu',
   options =>      # JavaScript object literal, sans curly braces
'minRows : 8,      # no validation, broken JavaScript will pass unnoticed
maxRows : 25,
openSpeed : 500'
);

print $jquery->link_elements;
print $jquery->script_src_elements;
print $jquery->document_ready;

# output

<link type="text/css" href="theme/ui.all.css" rel="stylesheet" media="screen" />
<link type="text/css" href="/css/jquery.mcdropdown.css" rel="stylesheet" media="all" />
<script type="text/javascript" src="/static/js/jquery.min.js" />
<script type="text/javascript" src="/js/jquery.mcdropdown.js" />
<script type="text/javascript" src="/js/jquery.bgiframe.js" />
<script type="text/javascript">
<![CDATA[
$(document).ready(function (){
$("#category").mcDropdown("#categorymenu",{
minRows : 8,
maxRows : 25,
openSpeed : 500
});
});
]]>
</script>

DESCRIPTION

Manage composition and insertion of link and script elements and the jQuery ready call into generated HTML.

Plugin modules provide support for individual jQuery plugins.

Framework plugins verify that the correct number of arguments will be passed to JavaScript plugin constructors but perform no validation beyond that.

This module provides four methods for inserting content into an HTML (or XHTML) document:

For the mcDropdown plugin, for example, would print the LINK elements for the jQueryUI and mcDropdown stylesheets. The output from this method should be inserted in the HEAD element of the document:

<link type="text/css" href="ui.all.css" rel="stylesheet" media="screen" />
<link type="text/css" href="jquery.mcdropdown.css" rel="stylesheet" media="all" />
script_src_elements( )

Prints all the SCRIPT elements with SRC attribute. The output from this method should be inserted in the HEAD element or somewhere before any calls to code in the JavaScript files:

<script type="text/javascript" src="jquery.min.js" />
<script type="text/javascript" src="jquery.mcdropdown.js" />
<script type="text/javascript" src="jquery.bgiframe.js" />
document_ready( )

Prints the jQuery $.ready function call and deletes any plugin objects created in this response cycle from the queue (otherwise they would accumulate with each request).

<![CDATA[
$(document).ready(function (){
$("#inputid").mcDropdown("#ulid");
});
]]>

Set transient_plugins to 0 if you wish to be able to fetch script and link elements and $.ready function calls more than once.

constructor_calls( )

Returns only the text of the constructor calls for insertion into existing code text. Useful for including the constructor calls in a template.

Set transient_plugins to 0 if you wish to be able to fetch script and link elements and $.ready function calls more than once.

Other accessors:

transient_plugins( )

Set or get the value of transient_plugins. Takes 1 or 0.

The data structure passed to the constructor provides the module with locations for all the script and style assets required to make the jQuery plugins work.

The 'src' and 'css' buckets can contain multiple list items.

SUPPORTED PLUGINS

The following jQuery plugins are supported in this version:

Superfish

http://users.tpg.com.au/j_birch/plugins/superfish/

The Supersubs jQuery plugin may be used in conjunction with Superfish to improve rendering of sub menu items.

FileamentGrpMenu

The FileamentGrpMenu framework plugin implements the interface required to generate a jQuery constructor for the Filament Group jQuery menu plugin.

http://www.filamentgroup.com/lab/jquery_ipod_style_and_flyout_menus/

mcDropdown

http://www.givainc.com/labs/mcdropdown_jquery_plugin.htm

funcliteral

Add literal text to document_ready method's output.

Support for other jQuery plugins will be added as the need arises. Contributions are welcome.

METHODS

new( %params )

Parameters

library

A reference to a hash:

{
    src => [ 'jquery.js' ],
    css => [
        { href => 'jquery-ui.css', media => 'all' }
    ]
}

This argument specifies the locations of the jQuery source and any stylesheets that should be included in your content.

These settings will be used to form script elements with the src attribute for any files included in the 'src' bucket, and link elements with the href attribute for any stylesheets included in the 'css' bucket. The script_src_elements and link_elements methods return the text of these HTML elements.

plugins

A reference to a hash with an element for each jQuery plugin that you want to manage with this module. Each element contains a library type data structure.

xhtml

Default: true

A boolean indicating whether markup should try to conform to XHTML or not.

transient_plugins

Default: true

If true, calling the document_ready or constructor_calls method clears the list of plugin constructors and assets (JavaScript and CSS files) returned by the script_src_elements, link_elements, document_ready and constructor_calls methods.

rel2abs_uri_callback

A reference to a subroutine that takes a (possibly) relative URI and returns and absolute URI.

In a Catalyst application this parameter might be passed with a value like:

rel2abs_uri_callback => sub { $c->uri_for(shift) }

config_plugin( %params )

Params

name

Required Str

Short name for the plugin module. JavaScript::Framework::jQuery::Plugin::Superfish's short name would be Superfish. This module calls require() against a package name formed by inserting name into the string "JavaScript::Framework::jQuery::Plugin::<name>".

no_library

Optional Bool

If true indicates that you are intentionally omitting the library parameter from the call to config_plugin.

Passing no_library with a true value and a library param in the same call to config_plugin will cause an exception.

The effect of omitting the library data when configuring the plugin is to omit the JavaScript and CSS assets from the html markup returned by the link_elements and script_src_elements methods. The only use case for this is the funcliteral plugin which is used to add to the text output by constructor_calls and document_ready and so has no assets associated with it.

Set static variables for a particular plugin type.

The plugin must be configured with config_plugin before calling construct_plugin or an exception will be raised.

construct_plugin( %params )

Append a new jQuery plugin wrapper object to the queue.

add_func_calls( @funccalls )

Add list of literal text containing function calls (technically you can add any text you like here, the text is opaque to this module).

Return markup for HTML LINK elements.

script_src_elements( )

Return markup for HTML SCRIPT (with SRC attr) elements.

document_ready( )

Return the jQuery $(document).ready(...) statement.

constructor_calls( )

Return the text of the jQuery plugin constructor calls for inclusion in an existing $(document).ready() text.

BUILD( )

See Moose::Cookbook::Basics::Recipe11

AUTHOR

David P.C. Wollmann, <converter42 at gmail.com>

BUGS

This is ALPHA code. The interface(s) may change or break.

Please report any bugs or feature requests to bug-javascript-framework-jquery at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=JavaScript-Framework-jQuery. 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 JavaScript::Framework::jQuery

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 David P.C. Wollmann, all rights reserved.

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