--------------------------------------------------------------

The WTemplate (widget template) module is a widget based
templating engine. It's planned for web templating, but
can be used for other areas (like console output or e-mail
generating), too.

The idea of a templating engine is to separate the code and
the output. You can assign variables to a template, and those
variables will be replaced in the template. Widgets are
template elements (looks like HTML elements), and if the
engine read one, then call a subroutine. You can define
parameters for the widgets - it will be passed to the
subroutine.

--------------------------------------------------------------

Basics
~~~~~~

It's a basic "element type" widget:

  my $template='
    <server:widgetname param1="2" param2="6" />
  ';

You can define a widget subroutine for it:

  new_widget 'widgetname', sub(%p, %v) {
    my $return;
    my $p1 = %p{'p1'};
    my $p2 = %p{'p2'};
    return $p1+$p2;
  };

Then just call the engine:

  my $output = $template.fill_with();


The value of the $output will be 8.

As templating engine is about passing variables, let's do it!
Here is our new template:

  my $template='
    <server:text id="varname" />
  ';

Then define the "text" widget:

  new_widget 'text', sub(%p, %v) {
    return %v{%p{'id'}};
  }

And let's call the template, with a variable:

  my %vars;
  %vars{'varname'} = 'Hello World!';
  my $output = $template.fill_with(%vars);

The $output will be 'Hello World!', as our widget
does nothing, but gets the hash's element with the
name defined by parameter 'id'.

In the widget, we get to paramaters, the first hash
contains the widget's parameters, coming from the template,
the second hash is the same one, we passed to the 'fill_with'
subroutine.

Just to know, 'text' is a predefined widget.

We've seen the element type widget, but there's another type,
the block type widget. The difference, that it has an opening
and closing tag, and - between them - some content:

  my $template='
    <server:repeater id="array">
      Hey, it will be repeated: <server:text id="variable" />
    </server>
  ';

As you can see, the content of our new 'repeater' widget contains
the 'text' widget. It's OK, will work, and a very common case.

Now, here's the definition of our repeater:

  new_widget 'repeater', sub(%p, %v) {
    my $return;
    for %v{%p{'id'}} {
      $return ~= %p{'_content'}.fill_with(%$_);
    }
    return $return;
  };

And let's call it:

  my %vars;
  %vars{'array'} = [ { variable => 'first' },
                     { variable => 'second' },
                     { variable => 'third' },
                     { variable => 'the last one' } ];
  my $output = $template.fill_with(%vars);

And the $output will be:

  Hey, it will be repeated: first
  Hey, it will be repeated: second
  Hey, it will be repeated: third
  Hey, it will be repeated: the last one

(Yes, the output won't be exactly like this, there will be some
empty lines - but it's not important now). Let's see, what happened!
We passed an array by the %vars hash to the templating engine (in this
case, the name of it was simply 'array'). Every element of this array
was a hash. Then the 'repeater' widget got it, and on every element
of this array, called the templating engine. The new templating engine
got the hashes inside the array.

Currently that's all, but a lot of things currently missing. I think,
some syntax will change, too.

Future
~~~~~~

I plan to develop this module, and extend it with parameter encoding
and decoding, as it is very important for the real life usage. As in
the future there will be other templating engines for Perl 6, I think,
that the current syntax is not the best for using them together, even,
if they interface will be different.

Other
~~~~~

The licence of this code is GPL.

Feel free to hack it, extend the documentation, and add some more default
widgets, too.

If you have any ideas, questions, just contact me:

  andras-dot-barthazi-at-wish-dot-hu-ngary