Greetings,
Here it is, the long-awaited (by me, anyway), release 0.6 of the HTML
module. There have been many changes to the module since its first
incarnations, but the basic organization and structure of the thing is
mostly the same. This is still pre-alpha code, so expect to find
bugs and expect things to change even more in the future.
The most radical change is in the name of the module. It is now called
HTML::Base (at least for the time being); see the changes list below for
details.
I will send the new module in a separate message, and will send yet another
message containing the new POD docs for the thing. I'll also make a
compressed archive and make it available on my FTP system. If you
want to grab it that way, anonymous FTP yourself over to
ftp.acoates.com
and grab the file
perl/HTML_0.6.tar.gz
The archive includes the module, the POD doc, and the list of changes.
Before I get to the changes we have made, I'd like to list first the
changes that were *not* made -- not *yet* anyway. These are things that
I personally want to see included in the module, but which I have either
not had the time to finish myself, or which I would like to hear more
discussion of before I spend much energy on them.
If you have any ideas, passions, rants, whatever on any of these topics,
please speak up:
* The module does no rules-checking concerning which HTML objects
may contain others. I have some ideas on this which I'll present a bit
later in a separate letter.
* I have not included all of the proposed HTML 3.0 tags, for a reason that's
related to my thoughts on rules-checking.
* There is no comprehensive test program for the module. (At the moment I
test new releases by re-building all of the pages of San Jose Living --
my web site at http://www.acoates.com/sjliving. Check it out if you want
to see what a few thousand lines of PERL and the HTML::Base module can do.)
* I have not split the module into smaller ones yet, mostly because I
haven't decided how to split it. Input please!
=============================================================================
Ok, now here are the changes from the Html.pm module, revision 0.5:
1. Comment tags are no longer printed with spaces. Example:
new HTML::Base::Comment
new HTML::Base::Text "This is a comment"
produces:
old way:
new way:
2. Header objects can be created either the old way:
new HTML::Base:Header 1;
or using the attribute 'Level' with the object syntax:
new HTML::Base:Header 'Level' => 1;
If used, "Level" must be the first attribute specified, otherwise it is
assumed that the first parameter is the level itself!
The same is true of Text objects; both of these examples work:
new HTML::Base:Text 'Text' => "This is some text";
new HTML::Base:Text "This is some text";
3. The module is now known as HTML::Base. All objects defined by the
module must now be prefixed with HTML::Base::. Yeah, I know it's wordy
and geeky, but it makes it much less likely that the object names will
clash with something else in your program.
The "use" statement for the module is now:
use HTML::Base
The default filename for the module is now:
$PERL5LIBS/HTML/Base.pm
where $PERL5LIBS = wherever you keep your PERL 5 modules (usually
/usr/local/lib/perl5).
4. Global functions (those at the HTML::Base level) have been separated
into "public" and "private", and the private ones have been renamed
to start with an underscore.
5. All HTML objects may now be created without inserting them into the
current HTML hierarchy. To create one of these "lone" objects, set
the Attribute "NoParent" to "1" (or anything else you'd like).
Example:
$loneparagraph = new HTML::Base::Paragraph 'NoParent' => 1;
Lone objects may also be created by copying existing objects:
$newloneparagraph = HTML::Base::copy_object ($loneparagraph);
The object being copied may be a lone object or a linked one, but the
new copy will always be "lone". Copies of objects contain copies of
all of the original object's children as well.
Note that copy_object may also be called in object syntax:
$newobj = $oldobj->copy_object;
6. Objects may be linked as children to other objects, even if the target
parent is not the "current" object. This can be done using the new
HTML::Base::link_to_parent subroutine, like this:
HTML::Base::link_to_parent ($loneobject, $targetparent);
If you want to link a "lone" object to the current object in the
hierarchy, use link_to_parent with get_current like this:
HTML::Base::link_to_parent ($loneparagraph, HTML::Base::get_current());
Be careful how you use HTML::Base::link_to_parent!
With HTML::Base::link_to_parent, you can build up collections of
lone HTML objects, link them up anyway you'd like, and then insert
the collection into the hierarchy anywhere you'd like. It's a bit
laborious, but you can do it (see below for an easier method using
cache_object). For example:
$loneparagraph = new HTML::Base::Paragraph 'NoParent' => 1;
$lonetext = new HTML::Base::Text "wowzo!", 'NoParent' => 1;
HTML::Base::link_to_parent ($lonetext, $loneparagraph);
HTML::Base::link_to_parent ($loneparagraph, HTML::Base::get_current());
7. Objects are now copied in the object cache, rather than just being
linked. This means you can use a cached object as many times as you'd
like, without worrying about all of the parent-child relationships.
The two calls used in caching are
HTML::Base::cache_object ($Name, $objectref) and
HTML::Base::use_object ($Name).
HTML::Base::cache_object makes a copy of the HTML object referenced by
$objectref, and stores a reference to the copy into the object cache
(a hash), giving it the name $Name.
HTML::Base::use_object retrieves a cached object, makes a copy of it,
and inserts the new copy into the HTML hierarchy, linking it as a child
of the "current" object. Note that all of these object copies are
recursive, so that a cached object will also contain all of its
original children. Here's an example:
$anchor = new HTML::Base::Anchor
'HREF' => 'http://www.acoates.com/sjliving';
new HTML::Base::Text 'Go to San Jose Living Home Page!';
HTML::Base::cache_object ('HomePageAnchor', $anchor);
... later on ...
HTML::Base::use_object ('HomePageAnchor');
The above code will make a copy of the Anchor, complete with its
Text child, and store it in the object cache under the name HomePageAnchor.
When used, both the Anchor and the Text are copied into the object
hierarchy and linked to the current object;
Note that the original object, the "cached" object and the "used" object
are three *different* objects. Each may be modified independant of
the others. They just start their lives as copied of each other.
8. The type of an HTML object can now be retrieved using the
HTML::Base::object_type call:
$objtype = HTML::Base::object_type($objectref);
The type returned is just the HTML object name, without the preceding
HTML::Base:: stuff. So in this example:
$para = new HTML::Base::Paragraph
$objtype = HTML::Base::object_type($para);
$objtype would equal 'Paragraph'.
Note that object_type may also be executed in object syntax:
$objtype = $para->object_type;
9. If you want to know whether a given object is a certain type, or if
any of its ancesters are of that type, you can now use the new
HTML::Base::contained_by call.
HTML::Base::contained_by ($objectref, $objecttype);
Example:
new HTML::Base::Preformatted;
new HTML::Base::Text "This is preformatted text";
new HTML::Base::Bold
$boldtext = new HTML::Base::Text "This is bold preformatted text";
if (HTML::Base::contained_by ($boldtext, 'Preformatted')) {
print "huh?\n";
}
10. The execute method now has a synonym, "realize". I just couldn't
let go of "execute", but I like "realize" as a better explanation
of what's really happening, so now we have both. They do the same
thing:
$objectref->execute;
or
$objectref->realize;
Similarly, there are two functions for realizing the entire hierarchy,
from the top down:
HTML::Base::execute();
or
HTML::Base::realize();
11. Newlines are now suppressed after Image objects, and in Comments, as
well as in Preformatted text blocks. This removes the little "ledger"
lines some browsers (ok, NetScape) place after images which are in
anchors if white space follows the Image tag, and also allows comments
to include "server-side include" statements.
12. Some NetScape and proposed HTML 3.0 tags and features have been added.
In the next release, I hope to provide the ability to choose a standard
and use it exclusively during a run of HTML. For the moment, though,
the module has all of HTML 2.0, with a smattering of NetScapisms and
3.0 proposals.
The new features added are:
- The Body object will now display the following attributes:
'BACKGROUND', 'BGCOLOR', 'TEXT', 'LINK', and 'VLINK'.
- The Break object accepts the 'CLEAR' attribute.
- The Header object now accepts the 'ALIGN' attribute.
- The Image object accepts the 'BORDER' attribute, along with the usual
'SRC', 'ALIGN', 'ALT', and ,'ISMAP'.
- The Paragraph object now accepts the 'ALIGN' attribute.
- Tables have been added. The new objects are:
- HTML::Base::Table
Attributes are 'BORDER', 'CELLPADDING', 'CELLSPACING', and 'WIDTH'.
- HTML::Base::TableCaption
Attributes are 'ALIGN', and 'VALIGN'.
- HTML::Base::TableData
Attributes are 'ALIGN', 'VALIGN', 'NOWRAP', 'COLSPAN', 'ROWSPAN',
and 'WIDTH'.
- HTML::Base::TableHeader
Attributes are 'ALIGN', 'VALIGN', 'NOWRAP', 'COLSPAN', 'ROWSPAN',
and 'WIDTH'.
- HTML::Base::TableRow
Attributes are 'ALIGN', and 'VALIGN'.
13. The debug mode messages have been expanded and (hopefully) made more
readable. Each object's "new" function calls standard functions which
begin and end a block of comments about the construction of the object.
This makes it easier to read a debug dump to see how your objects
are being born.
14. Documentation is now available in POD format.