This is a sample chapter of the Magicbook. The Magicbook can be purchased with Pro Dada, or by itself.
Dada Mail is quite flexible when it comes to changing the look and feel of the program itself, without having to plunge into the actual Perl program code. There are some exceptions, but we'll note them along the way.
What are templates? Templates are usually files that hold the text and, in our case, HTML that are used to display information. For Dada Mail, we're talking about the text that you see in your web browsers and in mail readers. Templates provide a mechanism to allow you to save this information in a place other than inline with the Perl programming code. This allows someone that does not have experience with Perl to considerably customize major portions of Dada Mail.
There are two basic places that Dada Mail uses templates in:
I'll be talking about both of course.
HTML Templates are what control what you see when you visit Dada Mail in your browser - most all of the text (copy) and layout are saved outside of the program in these templates.
When talking about HTML Templates, there are basically two types -
These templates control the basic layout/design of the HTML screens
Basically, the, ``content'' is put into the, ``wrapper''. Like, a candy bar!
By default, the List Template looks like this:
Look familiar? Good! The List Template is responsible for the look and feel of most of the HTML screens Dada Mail creates.
Some main points to get across:
Otherwise it will use the Default List Template. This is most prevalent in the Default Screen of Dada Mail, where no list is chosen by default.
We'll get into how to create your own Default List Template soon, but for now - let's stick to those two concepts.
Editing the List Template can be done a few ways:
You may edit the List Template by logging into your list control panel and going to:
Manage Appearance - Edit Template:
As you can see - there's a few ways to set your List Template - let's take one step back and dissect what a list template is.
A list template is an HTML document (a web page) with a few specific tags -
Tags in the list template look like this:
[tag]
it's a word with brackets around them. An impossibly simple example of a List Template is:
[dada]
And that's it! These tags will be replaced by information that they are standing in for. In this case, the tag, [dada] will be replaced by the actual content of the HTML screen you're viewing. Kinda neat.
Here's a list of tags that are available to you:
Adding these special Dada-specific tags to any HTML code will make this code into a Dada Mail List Template! Pretty simple.
Getting back to the Edit Template admin screen, you'll see you have a few options.
The three main options are:
Making changes to this HTML will change your List template - nothing to it!
This is a very helpful option if you want a template that has Server Side Includes, is created dynamically by a content management system, PHP, things like that. This template will be created dynamically before it reaches Dada Mail.
I use this option frequently myself, as it allows me to have a template who's design is automatically updated by Dreamweaver. The List Template HTML page that I specify in this option is also hooked up to Dreamweaver's own specific template system. When I make changes to the master Dreamweaver template, the List Template is updated. I then upload the List Template to my hosting account for Dada Mail to use. An easy way to integrate your layout/design with Dada Mail with minimum hassle.
The List Template is saved as a plain HTML file in the directory you set in the $TEMPLATES Config variable. This variable defaults to the $FILES if not set.
If you're looking for the list template that's specific for your list, look for the file that's named:
listshortname.template
Where, listshortname is the name of your template.
It is perfectly safe to edit this file directly, without the aid of Dada Mail.
If this file does not exist, it is perfectly safe to create it yourself. This file may not exist if you haven't yet played around with creating a template in the List Control Panel.
Whichever technique you use to edit your List Template, there's only a few key points you want to make sure you take into consideration:
When you start to edit your List Template, you usually have two choices: use the Default List Template as starting point and: start from scratch.
Since the Default List Template is fairly specific to Dada Mail - ie: it's not the same layout/design that the rest of your website has, it may be easier to use HTML that's similar to the pages that already exist on your website. We'll be going through both techniques.
Since version 2.9 of Dada Mail, the Default List Template has been writtin in XHTML, which means most all of the actual formatting and layout of the design is done in a separate stylesheet. Adding this stylesheet is as easy as placing the:
<!--[default_css]-->
in between the <head></head> tags of your template, like so:
<head>
<style type="text/css" media="all">
<!--[default_css]-->
</style>
</head>
This tag differs slightly from other tags used, since it's wrapped in HTML comment tags (<!-- -->). This is to actually facilitate testing of your Template when not using Dada Mail - the tag itself won't cause your design to not be invalidate if you send this off to an XHTML validator, such as http://validator.w3.org/
To change the stylesheet information outright, you have a few choices:
Not to get ahead of ourselves, but the stylesheet lives at:
dada/DADA/Template/templates/default_css.css
in the Dada Mail distribution.
You may also view the stylesheet indirectly by visiting:
http://example.com/cgi-bin/dada/mail.cgi/css
in your own installation of Dada Mail.
Editing this file will edit the stylesheet for Dada Mail. The rub is that this stylesheet is used globally - for everything in Dada Mail, so impacting this file will impact all other lists, the administration template - everything. This may be good thing, but be aware, regardless.
Great care has been made to make the stylesheet work with the Default List Template to allow an extraordinary amount of flexibility on what you can do with these pairings. Many of the techniques showcased at sites like http://csszengarden.com are possible with Dada Mail's Default List Template and Default Stylesheet.
<head>
<style type="text/css" media="all">
<!--[default_css]-->
</style>
<style type="text/css" media="all">
body {
background-color:#fff;
font-family:Verdana,Arial,'san-serif';
font-size:11px;
line-height:125%;
color: #006;
}
</style>
</head>
Easy enough - I just looked for the part of the stylesheet that has to do with what I want to change, copied it, pasted it into the template itself and changed what I wanted.
As I mentioned, the simplest List Template is just:
[dada]
If you'd like to start from scratch, that's your first ingredient. More realistically, you're probably going to start from an already created page from your website. Here's some steps to follow:
<head> <style type="text/css" media="all"> <!--[default_css]--> </style> <style type="text/css" media="screen">@import url(styles/style.css);</style> </head>
In this case, the page's original stylesheet was remotely linked. This is the technique that I use in the Dada Mail Support Site - have a look at the sourcecode of: http://mojo.skazat.com/cgi-bin/dada/mail.cgi
If you'd rather change all your list templates in one swoop, as well have HTML screens generated by Dada Mail that are not list-specific, you're going to have to changed the Default List Template. There are a few ways to do this:
All the HTML templates that you're able to edit easily are located in the:
dada/DADA/Template/templates/
directory of the distribution. There's a daunting amount of template files and we'll make heads and tails of all of them soon enough - we'll start with the Default List Template the Default Stylesheet.
The Default List Template file is saved as:
default_list_template.tmpl
The Default Stylesheet is saved as:
default_css.css
Modifying these files in place will change the layout/design of your Dada Mail installation globally. Neat.
A slightly better idea is to make a copy of the template files you want to change, and place them into the directory you set in the $TEMPLATES Config variable. Again, if this variable has not been set, you'll want to use the directory set in, $FILES.
Dada Mail will actually look in this directory first for all of the template files and then look into the, ``Master'' store of template files. This technique will work for every file that's in the:
dada/DADA/Template/templates
directory
This is a much smarter technique than the first one, so take advantage of it.
The $USER_TEMPLATE variable should hold either an absolute path to your Default List Template, or a URL to your Default List Template - examples:
$USER_TEMPLATE = '/home/account/www/my_template.html';
or:
$USER_TEMPLATE = 'http://example.com/my_template.html';
In these two examples, it's possible that each one could be pointing to the same template file, just in a different way. The example that uses a URL will have the same characteristics that you have when you specify the List Template in the List Control Panel: The web page will be preprocessed by the webserver before it reaches Dada Mail for display.
This technique also does not require you to edit the, ``Master'' Default List Template file, but it will only work for the Default List Template.
The admin template is very similar to the list template, although there is no web-based interface to editing it. The Admin Template also has a different set of tags available to use:
And that's about it.
As stated, there's no way to edit the Admin Template in Dada Mail via your web browser. The Admin Template does have a similar trick that the Default List Template has with its $USER_TEMPLATE variable, except the one for The Admin Template is called, $ADMIN_TEMPLATE. Like it's brethren, you can set this variable to an absolute path to a file, or a URL.
Content Templates vary slightly from Wrapper Templates in a few ways. As I've written, Content Templates are basically the, ``Stuff'' that gets plopped into the middle of the Wrapper Templates. Since they're templates, they do share many similarities.
Be aware that Content Templates are quite a bit more difficult to work with than the Wrapper Templates, but allow you to change almost every instance of HTML that Dada Mail produces. Very powerful.
Content Templates also use tags as place holders for information to be filled in later by Dada Mail for display. The tag syntax is different than the Wrapper Templates and we'll step through these differences slowly.
Content Templates are actually written in a completely different templating language than what is used for the simpler Wrapper Templates. This is because more sophisticated things are needed to be done to display the information Dada Mail needs to show you. Sophisticated as they are, it's still within the reach of someone with little or no programming experience.
The Templating Language is called: HTML::Template. If you'd like a complete overview and a pretty good walk through of what HTML::Template is all about, check out:
http://search.cpan.org/~samtregar/HTML-Template/Template.pm
Here's a very small introduction on HTML::Template tags and how they differ from Dada Mail's Wrapper Tags.
A tag used in Dada Mail's Wrapper templates may look like this:
[tag]
An HTML::Template tag may look like this:
<!-- tmpl_var tag -->
HTML::Template tags masquerade like HTML comments - you can pick them out from regular comments because they are prepended with the, tmpl_ thingy.
Instead of just providing a place holder for variables to be filled in, HTML::Template tags can also create loop structures - where similar data is displayed more than once and block statements, where part of the template may or may not be viewed, based on the value of the tag name. There are also tags that tell the templating system to include one template in another - meaning, one snippet of HTML/Template code can be used in more than one place in Dada Mail. These tags are what makes these templates incredibly powerful. For more information, please check the HTML::Template docs, mentioned above.
Content Templates also have an individual set of tags that aren't present in every template - you really can't make a table/chart of all the different tags, so you'll have to look at the template specifically and look for how the tags are used in context.
As I alluded to above, Content Templates live in the:
dada/DADA/Template/templates
directory of your distribution. There are about 80 templates and knowing which one to modify may be slightly confusing. Here's some very helpful advice:
<!-- begin default_screen.tmpl --> ...a whole bunch of stuff <!-- end default_screen.tmpl -->
If you see this, you'll know that the template used is called, ``default_screen.tmpl''. If you look into the Content Template directory, you'll find a file called, default_screen.tmpl. Modifying this template will change how this template is presented to you in the program!
flavor (f is shorthand for, ``flavor'') tells Dada Mail what it should do. Usually the values of either of those also correspond to the template being used.
For example, if the URL you're currently at is:
http://example.com/cgi-bin/dada/mail.cgi?f=send_email
f is set to, send_email and you'd be pretty sure that the template that you're viewing is called, send_email_screen.tmpl
Another example:
URL: http://example/cgi-bin/dada/mail.cgi?flavor=change_info
f is set to: change_info
Template Filename: change_info_screen.tmpl
Saying that, this rule of thumb isn't always the case, checking the source for those beginning and end HTML comment tags is a better way to figure this out.
You'll notice that both of the last two examples had filenames with, ``screen'' in them. This isn't always the case - you'll also see templates with filenames that have, ``widget'' in their filenames. There's a small difference. In Dada Mail, ``widget'' templates are usually a small chunk of code that's then included in another template file. ``screen'' templates are usually full pages that include these, ``widget''s. Widget templates are much more likely to be used by more than one ``screen'' template, so be careful to test your changes thoroughly when fiddling about.
Like the default_list_template.tmpl, you may edit the Wrapper Templates directly, although it is suggested that you make a copy of the file itself and save this copy to wherever you have set the $TEMPLATES Config variable.
Template Files do change between versions. If you do make a customization of a template, you may want to check the changes against the newest copy. The smaller the update to Dada Mail, the less likely a change has been made to the program. Consult the change logs of the program to see if the changes made were because of a bug in the Template code. If you do experience problems when using a customized template, you may want to double check that the changes you made aren't negatively impacting the usability of the program.
There are a number of HTML screens that are not available as templates themselves, but are available to edit on a per-list basis. In the list control panel, go to:
Manage Copy -> HTML Messages
These screens correspond to the sub/unsubscription process. You may globally change these screens in the Config.pm file. The names of the variables are:
There are a few instances where it is difficult to edit the HTML that's created in Dada Mail. Some HTML screens have not been templated out. The majority of this HTML is still inline with the Perl code - most likely inside the mail.cgi file.
Another place where inline HTML would be lurking is the dada/DADA/App/Error.pm file. Most all error messages are still located here.
Great care should be taken when attempting to edit these particular instances of HTML - since the HTML is inline with the Perl code, if you create a change that is not compatible with the Perl language, the program will give back an error and Dada Mail will be broken.
Now that we've uncovered the vastness of flexibility that is offered for HTML screens in Dada Mail, you shall now bare witness to the, sadly, relatively sparseness of customizing the email templates.
The email templates that are available to edit can be edited on a per-list basis in the List Control Panel, under:
Manage Copy -> Email Messages
You may also change these screens in the Config.pm file. The names of the variables are:
The, Mailing List Message Template actually has two versions - one for PlainText messages, and one for HTML messages. Depending on if you send a PlainText or HTML message, one or the other template will be used.
Pay particular attention to what is called in Dada Mail-land the, ``Opening'' and, ``Signature'' marks in each of these templates.
In the PlainText version of the Mailing List Message template, the opening mark is:
__
Or, spelled out, ``underscore''``underscore''``space''``newline''.
The signature mark is:
--
Or, spelled out, ``dash''``dash''``space''``newline''.
These marks come into play when you want to show these archived messages publicly. For PlainText messages, text located before the opening mark and after the signature mark will not be shown. This helps clean up the message, so you do not have to show the sub/unsub information, mailing list information, etc in each and every archive message shown publicly.
The opening and signature marks are slightly different in the HTML version of the Mailing List Message. The opening mark looks like this:
<!--opening--> ...text <!--/opening-->
and the signature mark looks like this:
<!--signature--> ...text <!--/signature-->
For HTML message no text located between either of these marks will be shown in the public archived messages.
The Mailing List Message Template also has a special tag, [message_body]. The Mailing List Message email template is much like the, ``Wrapper'' HTML Templates, where body copy is put in between the text of the template itself.
In this instance, the [message_body] tag will be replaced with the actually message as you have written it out when authoring your list message.
Other tags are available to be used in the Email Templates - a thorough list is available on the Manage Copy -> Email Messages screen.