/ 
HTML-Seamstress-6.112830
River stage one • 1 direct dependent • 1 total dependent
/ discuss::design-dilemma

Design dilemma in HTML::Seamstress (solved!)

Overview

HTML::Seamstress is a Perl module which supports HTML templating via tree-manipulations. It is based on HTML::Tree. The latest version of this module was inspired by the amazingly concise code that one can write with Class::DBI after setting up an object-oriented hierarchy.

Here are two samples of tree-based templating as the module is developed now:

Text substitution

In our first example, we want to perform simple text substitution on the HTML template document. The HTML file html/hello_world.htm has klass attributes which serve as compiler (kompiler?) hints to Seamstress:

<html>
<head>
  <title>Hello World</title>
</head>
<body>
<h1>Hello World</h1>
  <p>Hello, my name is <klass=content span id="name">dummy_name</span>.
  <p>Today's date is <klass=content span id="date">dummy_date</span>.
</body>
</html>

Seamstress compiles HTML to "html::hello_world" shell> seamc html/hello_world.htm Seamstress v2.91 generating html::hello_world from html/hello_world.htm

Now you simply use the compiled version of HTML with object-oriented accessors.

    use html::hello_world; 

    my $tree = html::hello_world->new; 
    $tree->name('terrence brannon')->date('5/11/1969')->as_HTML;

If-then-else with the highlander kompiler hint

The "highlander" kompiler hint is used to mark a subtree of HTML in which only one child should survive:

<span klass="highlander" id="age_dialog">
   <span id="under10">
      Hello, does your mother know you're 
      using her AOL account?
   </span>
   <span id="under18">
      Sorry, you're not old enough to enter 
      (and too dumb to lie about your age)
   </span>
   <span id="welcome">
      Welcome
   </span>
</span>

Compile and use the module:

use html::highlander;

my $tree = html::highlander->new;

$tree->age_dialog
   (
    [
     under10 => sub { $_[0] < 10} , 
     under18 => sub { $_[0] < 18} ,
     welcome => sub { 1 }
    ],
    $age
   )->as_HTML;

 # will only output one of the 3 dialogues based on which closure 
 # fires first

The dilemmas

Use of the klass tag as a kompiler hint

The biggest dilemma I have is whether to alter the HTML by use of the klass attribute as a kompiler hint. The original reason for writing Seamstress was to provide HTML templating via pure Perl and pure HTML. The original connection between the two was the id tag, a standard HTML attribute which must be unique for every element within an HTML4.01 document. The Java framework which inspired the development of Seamstress, XMLC, uses only standard class and id tags to generate Java accessors the HTML documents.

If I wanted to eliminate the klass attribute, then I would have to provide command line arguments to the Seamstress compiler to generate certain types of methods:

$> ./seamc -klass="name content" -klass="date content" hello_world.html

But that would get tedious when dealing with a ton of files.

So, even though the HTML would be slightly modified with the use of the klass tag, I think I would prefer that over having to supply kompiler hints at the shell.

Use of any magic whatsoever

Currently, Seamstress supplies accessors which are "intelligent" in two ways. One, they acts as getters or setters based on whether or not they are supplied arguments:

$tree->name ; # returns $tree->look_down(id => 'name');
$tree->name(12); # will call a setter method based on compiler hint

Two, they act as specialized setters based on compiler hints. Since there are numerous ways to "set" a node in a tree (you can set its contents, you can set its children's contents, you can set an attribute, you can delete all but one of the children, etc.), the tree operation that is called is based on the compiler hint.

However, it is not clear that all the extra work to make the inline code succint is worthwhile. The "magical" version of the hello_world.pm program is:

$tree->name('terrence brannon')->date('5/11/1969')->as_HTML;

The "plain Jane" version is:

$tree->get_name->replace_content('terrence brannon')
     ->get_date->replace_conent('5/11/69);

The plain version would simply have the Seamstress compiler create accessors for any HTML element in the document with an id tag. This plain version is very attractive for a number of reasons:

  • the HTML file has zero shock value to the HTML designer

  • no kompiler hints need to be written

  • no worry about needing to expand the kompiler hints into a mini-langauge

    Over time, mini-languages tend to need more and more. If all shortcuts and idioms are handled by library methods, then the full power of Perl can be brought to bear on any situation.

  • Similar to the way XMLC works for Java

    XMLC does not use any extra tags when creating DOM accessor classes to HTML files. The widespread success and usage of XMLC implies that none are necessary.

    If I wanted 100% compatibility with XMLC I would be using Terrence Mather's XML::DOM. However, HTML::ElementTable is an excellent module for imperative tree-building in Perl.

Conclusion

It is very depressing to have to rip out my compiler's guts. I spent a good amount of time building the compiler and code-generator and creating tests for it. Now, the compiler is going to be much simpler and all of the idiomatic processing will exist in standalone tree-processing libraries such as HTML::Element::Library (to be uploaded) or HTML::ElementTable.

However, I think this is a change for the better. In fact, it is nice to know that all tree processing actions will be handled like this:

$tree->$id_name->$library_method(@method_args);

instead of

$tree->$id_name(@args_to_magic_method)