Changes

=== SYNTAX ===

=== SYNTAX ===

<nowiki>Through the magic of autoloading, this class can make any html tag by calling a class method with the same name as the tag you want.  For examples, use "hr()" to make a "<HR>" tag, or "p(’text’)" to make "<P>text</P>".  This also means that if you mis-spell any method name, it will still make a new tag with the mis-spelled name. For autoloaded methods only, the method names are case-insensitive.

<nowiki>Through the magic of autoloading, this class can make any html tag by calling a class method with the same name as the tag you want.  For examples, use "hr()" to make a "<HR>" tag, or "p(’text’)" to make "<P>text</P>".  This also means that if you mis-spell any method name, it will still make a new tag with the mis-spelled name. For autoloaded methods only, the method names are case-insensitive.</nowiki><br />

If you call a class method whose name ends in "_group", this will be interpreted as an instruction to make a list of tags whose name are the part of the method name preceeding the "_group".  For example, calling "td_group( [’here’,’we’,’are’] )" results in "<TD>here</TD><TD>we</TD><TD>are</TD>" being generated.  The arguments that you call this method are exactly the same as for calling a method to make a single tag of the same name, except that the extra optional parameter "list" can be used to force an ARRAY ref of the new tags to be returned instead of a scalar.  The symantec difference is that any arguments whose values are ARRAY refs are interpreted as a list of values where each one is used in a separate tag; for a single tag, the literal ARRAY ref itself would be used.

The number of tags produced is equal to the length of the longest ARRAY ref passed as an argument.  For any other arguments who have fewer than this count, their last value is replicated and appended enough times as necessary to make them the same length.  The value of a scalar argument is used for all the tags.  For example, calling "input_group( type => checkbox, name => ’letters’, value => [’a’,’b’,’c’] )" produces ’<INPUT TYPE="checkbox" NAME="letters" VALUE="a"><INPUT TYPE="checkbox" NAME="letters" VALUE="b"><INPUT TYPE="checkbox" NAME="letters" VALUE="c">’.

All autoloaded methods require their parameters to be in named format.  These names and values correspond to attribute names and values for the new tags.  Since "no value" attributes are essentially booleans, they can have any true or false value associated with them in the parameter list, which won’t be printed.  If an autoloaded method is passed exactly one parameter, it will be interpreted as the "text" that goes between the tag pair (<TAG>text</TAG>) or after "start tags" (<TAG>text).  The same result can be had explicitely by passing the named parameter "text".  Most static (non-autoloaded) methods require positional parameters, except for start_html(), which can take either format.  The names of any named parameters can optionally start with a "-".

 

<nowiki>If you call a class method whose name ends in "_group", this will be interpreted as an instruction to make a list of tags whose name are the part of the method name preceeding the "_group".  For example, calling "td_group( [’here’,’we’,’are’] )" results in "<TD>here</TD><TD>we</TD><TD>are</TD>" being generated.  The arguments that you call this method are exactly the same as for calling a method to make a single tag of the same name, except that the extra optional parameter "list" can be used to force an ARRAY ref of the new tags to be returned instead of a scalar.  The symantec difference is that any arguments whose values are ARRAY refs are interpreted as a list of values where each one is used in a separate tag; for a single tag, the literal ARRAY ref itself would be used.</nowiki><br />

 

<nowiki>The number of tags produced is equal to the length of the longest ARRAY ref passed as an argument.  For any other arguments who have fewer than this count, their last value is replicated and appended enough times as necessary to make them the same length.  The value of a scalar argument is used for all the tags.  For example, calling "input_group( type => checkbox, name => ’letters’, value => [’a’,’b’,’c’] )" produces ’<INPUT TYPE="checkbox" NAME="letters" VALUE="a"><INPUT TYPE="checkbox" NAME="letters" VALUE="b"><INPUT TYPE="checkbox" NAME="letters" VALUE="c">’.</nowiki><br />

 

<nowiki>All autoloaded methods require their parameters to be in named format.  These names and values correspond to attribute names and values for the new tags.  Since "no value" attributes are essentially booleans, they can have any true or false value associated with them in the parameter list, which won’t be printed.  If an autoloaded method is passed exactly one parameter, it will be interpreted as the "text" that goes between the tag pair (<TAG>text</TAG>) or after "start tags" (<TAG>text).  The same result can be had explicitely by passing the named parameter "text".  Most static (non-autoloaded) methods require positional parameters, except for start_html(), which can take either format.  The names of any named parameters can optionally start with a "-".

</nowiki>

</nowiki>

==== make_html_tag_group( NAME[, PARAMS[, TEXT[, LIST]]] ) ====

==== make_html_tag_group( NAME[, PARAMS[, TEXT[, LIST]]] ) ====

This method is used internally to do the actual construction of html tag groups.  You can call it directly when you want faster code and/or more control over how tags are made.  The first argument, NAME, is a scalar that defines the actual name of the tag we are making (eg: ’br’); it is case-insensitive.  The optional second argument, PARAMS, is a HASH ref containing attribute names and values for the new tag; the names (keys) are case-insensitive.  Any attribute values which are ARRAY refs are flattened, and the number of tags made is determined by the length of the longest one.  The optional third argument, TEXT, is a HASH ref (or scalar) containing the text that goes between the tag pairs; it is not a tag attribute, but if its an ARRAY ref then its length will influence the number of tags that are made as the length of tag attribute arrays do.  The optional fourth argument, LIST, is a boolean/scalar which indicates whether this method returns the new tags in an ARRAY

This method is used internally to do the actual construction of html tag groups.  You can call it directly when you want faster code and/or more control over how tags are made.  The first argument, NAME, is a scalar that defines the actual name of the tag we are making (eg: ’br’); it is case-insensitive.  The optional second argument, PARAMS, is a HASH ref containing attribute names and values for the new tag; the names (keys) are case-insensitive.  Any attribute values which are ARRAY refs are flattened, and the number of tags made is determined by the length of the longest one.  The optional third argument, TEXT, is a HASH ref (or scalar) containing the text that goes between the tag pairs; it is not a tag attribute, but if its an ARRAY ref then its length will influence the number of tags that are made as the length of tag attribute arrays do.  The optional fourth argument, LIST, is a boolean/scalar which indicates whether this method returns the new tags in an ARRAY ref (one tag per element) or as a scalar (tags are concatenated together); a true value forces an ARRAY ref, scalar is the default.  This method knows which HTML tags are normally paired or not, which tag attributes take specified values or not, and acts accordingly.

      ref (one tag per element) or as a scalar (tags are concatenated together); a true value forces an ARRAY ref, scalar is the default.  This method knows which HTML tags are normally paired or not, which tag attributes take specified values or not, and acts accordingly.

 

=== COMPATABILITY WITH OTHER MODULES ===

=== COMPATABILITY WITH OTHER MODULES ===

The methods of this class and their parameters are designed to be compatible with any same-named methods in the popular CGI.pm class.  This class will produce identical or browser-compatible HTML from such methods, and this class can accept all the same argument formats.  Exceptions to this include:

The methods of this class and their parameters are designed to be compatible with any same-named methods in the popular CGI.pm class.  This class will produce identical or browser-compatible HTML from such methods, and this class can accept all the same argument formats.  Exceptions to this include:

* None of our methods are exported and must be called using indirect notation, whereas CGI.pm can export any of it’s methods.

* None of our methods are exported and must be called using indirect notation, whereas CGI.pm can export any of it’s methods.

* start_html() doesn’t support all the same arguments, but those that do have the same names.  However, the effects of the missing arguments can be easily replicated by making the appropriate tags

* start_html() doesn’t support all the same arguments, but those that do have the same names.  However, the effects of the missing arguments can be easily replicated by making the appropriate tags explicitly and handing them in via either the "head" or "body" arguments, where appropriate.  The common arguments are [’title’, ’author’, ’meta’, ’style’, ’head’, ’body’], in that order.

          explicitely and handing them in via either the "head" or "body" arguments, where appropriate.  The common arguments are [’title’, ’author’, ’meta’, ’style’, ’head’, ’body’], in that order.

* Our textarea() method is autoloaded, and doesn’t have the special symantecs that CGI.pm’s textarea() does.  However, any module who subclasses from this one can override textarea() with one that

* Our textarea() method is autoloaded, and doesn’t have the special symantecs that CGI.pm’s textarea() does.  However, any module who subclasses from this one can override textarea() with one that matches CGI.pm’s symantecs.  The "HTML::FormMaker" module does this.

          matches CGI.pm’s symantecs.  The "HTML::FormMaker" module does this.

* Autoloaded methods do not use the presence or absense of arguments to decide whether to make the new tag as a pair or as "start only".

* Autoloaded methods do not use the presence or absense of arguments to decide whether to make the new tag as a pair or as "start only".

* Autoloaded methods that make html tags won’t concatenate their arguments into a single argument under any circumstances, but in some cases the "shortcuts" of CGI.pm will do so.

* Autoloaded methods that make html tags won’t concatenate their arguments into a single argument under any circumstances, but in some cases the "shortcuts" of CGI.pm will do so.

* Currently we don’t html-escape any argument values passed to our tag making functions, whereas CGI.pm sometimes does.  While we expect our caller to do the escaping themselves where necessary,

* Currently we don’t html-escape any argument values passed to our tag making functions, whereas CGI.pm sometimes does.  While we expect our caller to do the escaping themselves where necessary, we may do it later in an update.

          we may do it later in an update.

* We go further to make the generated HTML human-readable by: 1. having each new tag start on a new line; 2. making all tag and attribute names uppercase; 3.  ensuring that about 20 often-used tag

* We go further to make the generated HTML human-readable by: 1. having each new tag start on a new line; 2. making all tag and attribute names uppercase; 3.  ensuring that about 20 often-used tag attributes always appear in the same order (eg: ’type’ is before ’name’ is before ’value’), and before any others.

          attributes always appear in the same order (eg: ’type’ is before ’name’ is before ’value’), and before any others.

=== COPYING ===

=== COPYING ===