More docs, split out table macro into its own file

META6.json

@@ -5,11 +5,14 @@
     "description" : "Generate simple, interleafable, HTML tags.",
     "authors" : [ "Mark Rushing" ],
     "provides" : {
-	"HTML::Tag"         : "lib/HTML/Tag.pm6",
-	"HTML::Tag::Tags"   : "lib/HTML/Tag/Tags.pm6",
-	"HTML::Tag::Macro"  : "lib/HTML/Tag/Macro.pm6",
+	"HTML::Tag"               : "lib/HTML/Tag.pm6",
+	"HTML::Tag::Tags"         : "lib/HTML/Tag/Tags.pm6",
+	"HTML::Tag::Macro"        : "lib/HTML/Tag/Macro.pm6",
+	"HTML::Tag::Macro::Form"  : "lib/HTML/Tag/Macro/Form.pm6",
+	"HTML::Tag::Macro::List"  : "lib/HTML/Tag/Macro/List.pm6",
+	"HTML::Tag::Macro::Table" : "lib/HTML/Tag/Macro/Table.pm6",
     },
     "depends" : [ "HTML::Entity" ],
     "resources" : [ ],
-    "source-url" : "ssh://git.orbislumen.net/opt/git6/HTML-Tag.git"
+    "source-url" : "git://github.com/adaptiveoptics/HTML-Tag.git"
 }

doc/HTML/Tag.pod6

@@ -30,10 +30,43 @@ their :text by passing alternating string text and tag objects as a
 list. Tag objects passed this way I<should not> have C<.render> called
 on them first to avoid the HTML special characters being escaped.
 
+Not all attributes of every HTML tag is supported, just the most
+common. It enforces very little. It is meant to help minimize clutter
+in code for those who are not using html template classes or who wish
+to dynamically generate segments of html code.
+
+Please see the POD documentation for each macro for more details on
+macro use.
+
+Also, an HTML::Tag::Exports can be used to export the symbol "tag"
+into your scope which shortens HTML::Tag::<thing> creation to
+tag('thing', |%opts)
+
 =head1 TAGS
 
+HTML::Tag::Tags will give you all tag classes defined. They can be
+instantiated with HTML::Tag::<whatever>.new and take options matching
+their normal html attributes.
+
+Tags can be combined into one another by placing them into another
+tag's :text attribute. Tags are then recursively rendered when .render
+is called on the furthest-outward containing tag (such as
+HTML::Tag::html which represents an entire page).
+
+C<HTML::Tag::Macro::CSS> will generate a CSS link.
+
+C<HTML::Tag::Macro::Table> will help generate tables.
+
+C<HTML::Tag::Macro::List> will help generate lists.
+
+C<HTML::Tag::Macro::Form> will help generate form and do some form
+variable handling.
+
 =head1 MACROS
 
+Please see individual macro files for more thorough documentation on
+each macro.
+
 =head2 HTML::Tag::Macro::CSS
 
 Renders a normal CSS file link that can be wrapped into a html head element:
@@ -87,4 +120,64 @@ passed along to the normal HTML::Tag::table object.
 NO CHECKING IS PERFORMED FOR A CONSISTENT NUMBER OF ELEMENTS IN EACH
 ROW
 
+=head2 HTML::Tag::Macro::List
+
+Generates an ordered or unordered HTML list from a supplied array, or
+constructs the array for you by repeated calling of the item() method.
+
+    =begin code
+    my $list = HTML::Tag::Macro::List.new;
+    $list.link(:to('http://somewhere'), :text('rainbows'));
+    $list.link(:to('http://elsewhere'), :text('snails'), :class('highlight'));
+    $list.render;
+
+    # .. or ..
+
+    my @fruit = 'fingers', 'sofa', 'airliner';
+    my $html = HTML::Tag::Macro::List.new(:items(@fruit)).render;
+    =end code
+
+The lists have a special method called link() that makes HTML::Tag::a
+links that are surrounded by list elements since this is a common way
+to generate HTML menus.
+
+=head2 HTML::Tag::Macro::Form
+
+Generates forms based upon a definition variable passed in. This
+variable must be an array of hashes.
+
+The array of hashes represents one form element per hash in the
+array. Labels are automatically generated for all form elements by
+default.
+
+The hash key represents the HTML name of the hash by default, and the
+input variable if given, etc. That key's value represents options for
+that form element.
+
+    =begin code
+    use HTML::Tag::Macro::Form;
+
+    my $form = HTML::Tag::Macro::Form.new(:action('/hg/login/auth'),
+                                          :input(%.input));
+    $form.def = ({username => {}},
+                 {password => { type => 'password' }},
+                 {submit   => { value => 'Login',
+                                type  => 'submit',
+                                label => '' }}
+                );
+
+    $form.render;
+    =end code
+
+Most certainly a work in progress.
+
+=head1 AUTHOR
+
+Mark Rushing mark@orbislumen.net
+
+=head1 LICENSE
+
+This is free software; you can redistribute it and/or modify it under
+the Artistic License 2.0.
+
 =end pod

lib/HTML/Tag.pm6

@@ -102,3 +102,16 @@ role HTML::Tag::generic-tag[$T]
 	return $tag ~ "</$T>";
     }
 }
+
+=begin pod
+
+=head1 AUTHOR
+
+Mark Rushing mark@orbislumen.net
+
+=head1 LICENSE
+
+This is free software; you can redistribute it and/or modify it under
+the Artistic License 2.0.
+
+=end pod

lib/HTML/Tag/Exports.pm6

@@ -7,3 +7,39 @@ sub tag($tag-name = 'p', *%opts) is export {
     HTML::Tag::{$tag-name}.new(|%opts);
 }
 
+=begin pod
+
+=head1 NAME HTML::Tag::Exports
+
+=head1 SYNOPSIS
+
+    =begin code
+    use HTML::Tag::Exports;
+
+    say tag(text => 'I am a paragraph').render;
+    # <p>I am a paragraph</p>
+
+    say tag('span', :text('In a span zone'));
+    # <span>In a span zone</span>
+    =end code
+    
+=head1 DESCRIPTION
+
+Use'ing HTML::Tag::Exports will place the "tag" key into your current
+scope, and this tag will give you a shorthand for calling
+C<HTML::Tag::<whatever>.new> -- in that you instead call
+C<tag('whatever')> instead.
+
+Options given after the tag name string, which must be the first
+parameter, are passed along as-is to the HTML tag.
+
+=head1 AUTHOR
+
+Mark Rushing mark@orbislumen.net
+
+=head1 LICENSE
+
+This is free software; you can redistribute it and/or modify it under
+the Artistic License 2.0.
+
+=end pod

lib/HTML/Tag/Macro.pm6

@@ -11,39 +11,6 @@ class HTML::Tag::Macro::CSS is HTML::Tag::link
     }
 }
 
-class HTML::Tag::Macro::Table
-{
-    has @.rows is rw;
-    has $.table-opts is rw = {};
-
-    method row(Bool :$header = False,
-	       Hash :$td-opts,
-	       Hash :$tr-opts = {},
-	       *@cols) {
-
-	my @col-objects;
-	for @cols.kv -> $i, $col {
-	    my $opts = $td-opts{$i}:exists ?? $td-opts{$i} !! {}  ;
-	    if ($header) { @col-objects.push: HTML::Tag::th.new(:text($col), |$opts) }
-	    else         { @col-objects.push: HTML::Tag::td.new(:text($col), |$opts) }
-	}
-	@!rows.push: HTML::Tag::tr.new(:text(|@col-objects), |$tr-opts);
-    }
-
-    method rows(Hash :$td-opts,
-		Hash :$tr-opts = {},
-		*@rows) {
-
-	@rows.map: { self.row(:td-opts($td-opts),
-			      :tr-opts($tr-opts),
-			      |$_ );
-		   }
-    }
-
-    method render() {
-	HTML::Tag::table.new(:text(|@!rows), |$!table-opts).render;
-    }
-}
 
 =begin pod
 
@@ -59,28 +26,6 @@ class HTML::Tag::Macro::Table
     # <link rel="stylesheet" href="css/file.css" type="text/css">
     =end code
 
-=head2 Table
-
-    =begin code
-    use HTML::Tag::Macro::Table;
-    my $table = HTML::Tag::Macro::Table.new;
-    my @data = 'Val 1', 'Val 2', 'Total';
-    $table.row(:header, @data);
-    @data = 111, 22, 133;
-    $table.row(@data);
-    $table.render;
-
-    # <table><tr><th>Val 1</th><th>Val 2</th><th>Total</th></tr><tr><td>111</td><td>22</td><td>133</td></tr></table>
-
-    # ... or replace @data above and use rows() for multiple rows with 2-d array
-    @data = ((111, 22, 133),
-	     (222, 33, 255));
-    $table.rows(@data);
-    $table.render;
-
-    # <table><tr><th>Val 1</th><th>Val 2</th><th>Total</th></tr><tr><td>111</td><td>22</td><td>133</td></tr><tr><td>222</td><td>33</td><td>255</td></tr></table>   
-    =end code
-
 =head1 DETAIL
 
 Macros are created and rendered tags but offer some automation.
@@ -93,50 +38,18 @@ HTML::Tag::Macro::CSS accepts the same options as the ::link tag, but
 additionally :rel (defaulting to "stylesheet") and :type (defaulting
 to "text/css".
 
-=head2 Table
-
-Creates a combination of ::th ::td ::tr tags swallowed by a ::table
-tag to help automate the creation of an HTML table.
-
-HTML::Tag::Macro::Table has 2 methods: C<row()> and C<rows()>.
+=head2 other macros
 
-row(@array_of_table_row_data) - each element of the array will be
-surrounded by ::td tags in the row.
+See the macro subdirectory
 
-row(:header) designates the row as an HTML header row (so ::th tags
-will be u sed instead of ::td tags for that row).
-
-row(:td-opts) applies ::td tag options to select ::td elements
-generated in the row. That element is selected by specifying the
-numeric key and the value becomes the options to apply. For example,
-to apply options to the second td element,
-
-    =begin code
-    $td-opts = %( 2 => {class => 'pretty'});
-    =end code
-
-row(:tr-opts) applies ::tr tag options to the row.
-
-If you want to generate the table by specifying multiple rows, you can
-do so with a 2-d array, where each element is a list of table data,
-using the rows() method instead of row().
-
-    =begin code
-    @data = ((34, 53, 23),
-             (43, 23, 55),
-             (27, 32, 66));
-    $table.rows(@data);
-    =end code
-
-The rows() method also takes the :td-opts and :tr-opts options, but
-they are passed to every single row.
+=head1 AUTHOR
 
-Table options can be specified when instantiating the table macro with
-new using the (:table-opts) hash.
+Mark Rushing mark@orbislumen.net
 
-=head1 AUTHOR
+=head1 LICENSE
 
-Mark Rushing seatek@gmail.com
+This is free software; you can redistribute it and/or modify it under
+the Artistic License 2.0.
 
 =end pod
-    
+

lib/HTML/Tag/Macro/Form.pm6

@@ -119,6 +119,11 @@ below. Detailed descriptions follow.
                   class   => undef,
                   value   => undef,
                   var     => undef,
+		  required     => False,
+		  autofocus    => False,
+		  tag-after    => HTML::Tag::<whatever>,
+		  tag-before   => HTML::Tag::<whatever>,
+		  swallowed-by => HTML::Tag::<whatever>,
                 }
        },
     );
@@ -234,6 +239,11 @@ Returns the rendered form with all its elements and values.
 					   
 =head1 AUTHOR
 
-Mark Rushing seatek@gmail.com
+Mark Rushing mark@orbislumen.net
+
+=head2 LICENSE
+
+This is free software; you can redistribute it and/or modify it under
+the Artistic License 2.0.
 
 =end pod

lib/HTML/Tag/Macro/List.pm6

@@ -126,6 +126,11 @@ tag and returns the string.
 
 =head1 AUTHOR
 
-Mark Rushing seatek@gmail.com
+Mark Rushing mark@orbislumen.net
+
+=head2 LICENSE
+
+This is free software; you can redistribute it and/or modify it under
+the Artistic License 2.0.
 
 =end pod