Permalink
Browse files

Added some docs

  • Loading branch information...
1 parent aea1e92 commit 3221cdddeeb0a2db5ffc274b5c44ec995848b165 @perlpilot committed Dec 7, 2011
Showing with 114 additions and 9 deletions.
  1. +114 −9 lib/Dancer/Plugin/TTHelpers.pm
@@ -1,17 +1,116 @@
package Dancer::Plugin::TTHelpers;
# ABSTRACT: Useful routines for generating HTML for use with Dancer + TT
+=head1 SYNOPSIS
+
+In your Dancer application's MyApp.pm file ...
+
+ package MyApp;
+ use Dancer ':syntax';
+ use Dancer::Plugin::TTHelpers;
+
+and in your application's views ...
+
+ <!-- in layout.tt -->
+ <% css('foo') %>
+ <% js('bar') %>
+
+ <!-- in index.tt -->
+ Name: <% text('name') %></br>
+ Shirt Size: <% radio('size', sizes) %></br>
+ Quantity: <% select('quantity', quants) %></br>
+ <!-- etc. -->
+
+=head1 DESCRIPTION
+
+B<NOTE>: this module is very alpha code. I<Use at your own risk>
+
+=head2 Background
+
+I was working on a Dancer app and got tired of using the normal Template
+Toolkit mechanisms for generating forms. Also, I got tired of writing
+the boiler-plate for CSS and Javascript. Then I remembered when I
+was working with Rails a few years ago, there were some handy
+routines for generating this stuff, so after looking around briefly
+for something to fit the bill, I decided to make my own.
+
+This was the result.
+
+=head2 The Helpers
+
+By using this module in your Dancer app, new routines are made available from
+within your views that aid in generating HTML for forms and the standard HTML
+required for include CSS or Javascript files.
+
+Following are the list of routines available from within you templates:
+
+=over
+
+=item C<css(FILE, [ IE_COND ], [ ATTRIBUTES ])>
+
+Outputs a C<< <link> >> tag. C<FILE> should be the name of a CSS
+file within the F<public/css> directory of your app. If C<FILE> does not
+end with C<.css>, then it is appended. If COND is specified, the CSS link is
+surrounded with appropriate comments for IE. Any additional attributes for the
+C<< <link> >> tag may be specified as a hashref.
+
+Example usage:
+
+ <% css('print', { media => "print" }) %>
+ <% css('ie', 'lt IE 8' { media => "screen,projection" }) %>
+
+which results in the following output:
+
+ <link rel='stylesheet' href='http://localhost:3000/css/print.css' type='text/css' media="print" />
+<!--[if lt IE 8]><link rel='stylesheet' href='http://localhost:3000/css/ie.css' type='text/css' media="screen,projection" /><![endif]-->
+
+=item C<js(FILE, [ IE_COND ], [ ATTRIBUTES ])>
+
+Outputs a C<< <script> >> tag with appropriate C<language> and C<type>
+attributes for javascript. C<FILE> should be the name of a javascript file
+located within F<public/javascripts>. If C<FILE> does not end with C<.js>,
+then it is appended. If COND is specified, the CSS link is surrounded
+with appropriate comments for IE. Any additional attributes for the
+C<< <script> >> tag may be specified as a hashref.
+
+Example usage:
+
+ <% js('jquery') %>
+
+which results in the following output:
+
+ <script languages='javascript' src='http://localhost:3000/js/jquery.js' type='text/javascript'></script>
+
+=item radio
+
+=item text
+
+=item select
+
+=item hidden
+
+=item checkbox
+
+=item button
+
+=back
+
+=cut
+
use strict; use warnings;
use 5.10.0;
use Dancer ':syntax';
use Try::Tiny;
+use Scalar::Util qw/ blessed /;
sub make_attribute_string {
return defined $_[0]
? join " ", map { $_ . '="' . $_[0]->{$_} . '"' } keys %{$_[0]}
: "";
}
+# NOTE: The first hashref we come across is assumed to be the
+# attributes
sub process_attributes {
for my $i (0..$#_) {
if (ref $_[$i] eq 'HASH') {
@@ -55,8 +154,9 @@ hook 'before_template' => sub {
};
$tokens->{radio} = sub {
+ my $obj = shift if blessed $_[0];
my $attributes = &process_attributes;
- my ($obj, $name, $values, $sep) = @_;
+ my ($name, $values, $sep) = @_;
$sep ||= '';
my ($i, @ret) = 0;
my $on = do { try { $obj->$name } } // @{$values}[0];
@@ -70,16 +170,18 @@ hook 'before_template' => sub {
};
$tokens->{text} = sub {
+ my $obj = shift if blessed $_[0];
my $attributes = &process_attributes;
- my ($obj, $name, $value) = @_;
+ my ($name, $value) = @_;
my $idx = compute_idx($obj);
my $val = do { try { $obj->$name } } // $value // "";
return qq(<input type="text" name="$name$idx" value="$val" $attributes />);
};
$tokens->{select} = sub {
+ my $obj = shift if blessed $_[0];
my $attributes = &process_attributes;
- my ($obj, $name, $options, $key, $value) = @_;
+ my ($name, $options, $key, $value) = @_;
my $idx = compute_idx($obj);
my $str = $name ? qq(<select name="$name$idx" $attributes>) : "<select>";
my $on = $obj && $name ? ($obj->$name // "") : "";
@@ -99,22 +201,25 @@ hook 'before_template' => sub {
};
$tokens->{button} = sub {
- my ($value, $attrs) = @_;
- my $attributes = make_attribute_string($attrs);
+ my $obj = shift if blessed $_[0];
+ my $attributes = &process_attributes;
+ my ($value) = @_;
return qq(<input type="button" value="$value" $attributes />);
};
$tokens->{hidden} = sub {
- my ($obj,$name,$value, $attrs) = @_;
+ my $obj = shift if blessed $_[0];
+ my $attributes = &process_attributes;
+ my ($name, $value) = @_;
my $idx = compute_idx($obj);
- my $attributes = make_attribute_string($attrs);
return qq(<input type="hidden" name="$name$idx" value="$value" $attributes />);
};
$tokens->{checkbox} = sub {
- my ($obj, $name, $checked, $attrs) = @_;
+ my $obj = shift if blessed $_[0];
+ my $attributes = &process_attributes;
+ my ($name, $checked) = @_;
my $idx = compute_idx($obj);
- my $attributes = make_attribute_string($attrs);
$checked = try { $obj->$name } catch { $checked // 1 };
$attributes .= " checked" if $checked;
return qq(<input type="checkbox" name="$name$idx" value="1" $attributes />);

0 comments on commit 3221cdd

Please sign in to comment.