Added some docs

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 />);