Name

DADA::Template::Widgets

Description

Holds commonly used HTML 'widgets'

Subroutines

list_popup_menu

returns a popup menu holding all the list names as labels and list shortnames as values

screen

screen() is a slight wrapper around the HTML::Template module. See:

http://search.cpan.org/~samtregar/HTML-Template/Template.pm

screen has somewhat of a similar API, but a bit simplier - for example, it also includes support for HTML::Template::Expr:

http://search.cpan.org/~samtregar/HTML-Template-Expr/Expr.pm

with just a paramater change. The default is to use HTML::Template. No other HTML::Template::* modules are used.

I won't delve into great detail on how to make a HTML::Template or HTML::Template::Expr template, but I would encourage you to look into the docs for the two above modules for the jist. Any valid HTML::Template and/or HTML::Template::Expr template can be used for screen.

Finally screen has some (always optional) hooks into Dada Mail's Settings and Subscribers backends, so you may tell screen to use that information, instead of passing things in the -vars paramter.

Anyways:

 require DADA::Template::Widgets; 
 print DADA::Template::Widgets::screen(\
    {
    # ...
    }
 );

screen returns back a string with the final result of the template and basically what HTML::Template's output will return. No post processing is done after that.

Getting data to screen can be done in basically two ways:

Via the -data paramater:

 my $scalar = 'This is my information!'; 
 print DADA::Template::Widgets::screen(
    {
        -data => \$scalar,
    }
 );

The information in -data needs to be a reference to a scalar value. In H::T, it maps to the scalarref paramater.

Via the -screen paramater:

 print DADA::Template::Widgets::screen(
    {
        -screen => 'somefile.tmpl',
    }
 );

which should be a filename to whatever template you'd like to use.

In H::T, it maps to the filename paramater.

If the data you're giving screen is an HTML::Template::Expr template, you may also pass over the, -expr paramater with a value of, 1:

 print DADA::Template::Widgets::screen(
    {
        -screen => 'somefile.tmpl',
        -expr   => 1, 
    }
 );

Variables to be used in the template can be passed using the, -vars paramater, which maps to the, H::T paramater, param. -vars should hold a reference to a hash:

 my $scalar = 'I wanted to say: <!-- tmpl_var var1 -->'; 
 print DADA::Template::Widgets::screen(
    {
        -data => \$scalar,
        -vars   => {var1 => "This!"}, 
    }
 );

This will print:

 I wanted to say: This!

There is one small HTML::Template filter that turns the very very simple (oldstyle) Dada Mail template-like files into something HTML::Template can use. In the beginning (gather 'round, kids) Dada Mail didn't have a Templating system (really) at all, and just used regex search and replace - sort of like everyone did, before they knew better. Old style Dada Mail variables looked like this:

 [var1]

These oldstyle variables will still work, but do remember to pass the, -dada_pseudo_tag_filter with a value of, 1 to enable this filter:

 my $scalar = 'I wanted to say: [var1]'; 
 print DADA::Template::Widgets::screen(
    {
        -data                   => \$scalar,
        -vars                   => {var1 => "This!"}, 
        -dada_pseudo_tag_filter => 1, 
    }
 );

This will print:

 I wanted to say: This!

My suggestion is to try not to mix the two dialects and note that we'll probably be moving to using the H::T default template conventions, so as to make geeks and nerds more comfortable with the program. Saying that, you can mix the two dialects and everything should work. This may be interesting in a pinch, where you want to say something like:

 Welcome to [boring_name]
 
 <!-- tmpl_if boring_description --> 
  My boring description: 
  
    [boring_description]
    
 <!--/tmpl_if-->

since the oldstyle Dada Mail template stuff didn't have any sort of idea of a if block. I'm not really considering adding support either.

And that's basically screen. Learn HTML::Template and memorize the mappings and you'll be right at home.

A few things to mention:

Many of the Dada Mail modules require you to pass a listshortname some where - screen doesn't, and this is by design - it attempts to be separate from any Dada Mail backend or information inside.

There are hooks in screen to pass variables in the template from the settings and subscriber backend, but they're limited and absolutely optional, but are handy for shortcuts and hey, what isn't programming but shortcuts?

To tell screen to use a specific subscriber information, you have two different methods.

The first is to give the paramaters to *which* subscriber to use, via the -subscriber_vars_param:

 print DADA::Template::Widgets::screen(
    {
    -subscriber_vars_param => 
        {
            -list  => 'listshortname', 
            -email => 'this@example.com', 
            -type  => 'list',
        }
    }
 );

This will basically have screen call the DADA::MailingList::Subscribers::* get_subscriber method and pass the paramaters set in this hashref. It's best to make sure the subscriber exists, or you may run into trouble.

The subscriber information will be passed to HTML::Template via its param method. The name of the paramaters will be appended with, subscriber., so as not to clobber any other variables you're passing, so if you have a field named, "first_name", you can use a template var that looks like this:

 <!-- tmpl_var subscriber.first_name -->

or:

 [subscriber.first_name]

The following won't work:

 <!-- tmpl_var first_name -->

 [first_name]

Note: that this dot notation isn't using HTML::Template::Plugin::Dot, but is just a variable naming convention, to give the subscriber information some sort of namespace.

The other magical thing that will happen, is that you'll get a new variable to be used in your template called, subscriber, which is a array ref of hashrefs with name/value pairs for all your subscriber fields. So, this'll allow you to do something like this:

 <!-- tmpl_loop subscriber --> 
 
  <!-- tmpl_var name -->: <!-- tmpl_value -->
 
 <!--/tmpl_loop-->

and this will loop over your Subscriber Profile Fields.

If you'd like, you can also pass the Subscriber Profile Fields information yourself - this may be useful if you're in some sort of recursive subroutine, or if you already have the information on hand. You may do so by passing the, -subscriber_vars paramater, instead of the -subscriber_vars_param paramater, like so:

 use DADA::MailingList::Subscribers; 
 my $lh = DADA::MailingList::Subscribers->new({-list => 'listshortname'}); 
 
 my $subscriber = $lh->get_subscriber(
                      {
                         -email  => 'this@example.com', 
                         -type   => 'list', 
                         -dotted => 1, 
                       }
                   ); 
 
 use DADA::Template::Widgets; 
 print DADA::Template::Wigets::screen(
 
           { 
                -subscriber_vars => $subscriber,
           }
       );

The, subscriber variable will still be magically created for you.

The -subscriber_vars paramater is also a way to override what gets printed for the, subscriber. variables, since nothing is done to check the validity of what you're passing. So, keep that in mind - all these are shortcuts and syntactic sugar. And we like sugar.

A similar thing can be used to retrieve the list settings of a particular list:

 print DADA::Template::Widgets::screen(
    {
    -list_settings_vars_param => 
        {
            -list  => 'listshortname', 
        }
    }
 );

or:

 use DADA::MailingList::Settings; 
 my $ls = DADA::MailingList::Settings->new({-list => 'mylist'}); 
 
 my $list_settings = $ls->get(
                         -dotted => 1, 
                     ); 
 
 use DADA::Template::Widgets; 
 print DADA::Template::Wigets::screen(
 
           { 
                -list_settings_vars => $list_settings,
           }
       );

This will even work, as well in a template:

 <!-- tmpl_loop list_settings --> 
 
    <!-- tmpl_var name -->: <!-- tmpl_var value -->
 
 <!-- /tmpl_loop -->

Again, much of this is syntactical sugar and magic, but a lot of it is to keep organized the various sources of your template data. Only at the very final time is all this information folded into itself.

The precendence for these various variables is:

-list_settings_vars
-subscriber_vars
-vars

Which means, if you (for whatever weird reason) want to override anything in either the -list_settings_vars or -subscriber_vars, you can in -vars

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.