Question
How do I add a new page type with its own custom template?
Answer
You can add a new type of page or file with a custom plugin.
Big Medium's plugin architecture lets you customize and add
new file outputs when Big Medium generates its pages. This is the same
system, for example, that generates printer-friendly and email-this
pages for each page of the site.
Create an E-Mail Friendly Version of the Homepage
Say that we're running a community newspaper, and we have a big mailing list of
suscribers who have asked us to send them a weekly email showcasing our
homepage contents.
We also have an email manager (like DadaMail)
which can send html pages to our mailing list by giving it the URL.
Trouble is, what looks good for the Web doesn't always look so good in e-mail.
So we want to create a good-looking, email-specific version of our
homepage. It would be great if we could get Big Medium to generate the HTML
for this mailing for us automatically, and then we'll just tell DadaMail
to send it for us.
This tutorial will walk through the process of telling Big Medium to generate
another version of the homepage based on a new email template that we'll
provide.
Our Template
The specifics of how to create an e-mail friendly webpage are beyond the
scope of this tutorial, but here are some useful pointers for how you
can build email-friendly email messages and, in particular, to safely
incorporate CSS styles into your email templates:
For this exercise, we'll just use a very simple XHTML template that
shows only the homepage title, content and links, with no real design.
Feel free, of course, to spiff it up with your own design markup.
Important: You should use the same link widgets on this page that you
use in the "real" homepage template. If you're using Big Medium's default
template, that means:
<%spotlight%><%links%><%morelinks%>
Here's our template:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title><%title%></title>
</head>
<body>
<%headline%>
<%content%>
<hr />
<%spotlight%>
<hr />
<%links%>
<%morelinks%>
<hr />
<%footer%>
</body>
</html>
Name this template _home_email.txt and add it alongside Big Medium's other
default HTML templates:
moxiedata/templates/site_templates/HTML/_home_email.txt
Registering the Template
Now that we've got the template, we need to tell Big Medium that it exists
and what to do with it. To do that, we'll create a plugin module named
BigMed::Plugin::HomeEmail.
The module needs to register the template with Big Medium's HTML-building
class (BigMed::Format::HTML). It also needs to teach Big Medium
how to say the name of the template and, if we want, show a description
of it in the template editor. Here's the result:
package BigMed::Plugin::HomeEmail;
use strict;
use warnings;
use BigMed::Format::HTML;
use BigMed::Language;
#register the template under the internal name "home_email" to
#correspond to the name of our template file: _home_email.txt
BigMed::Format::HTML->register_template(
{ name => 'home_email', #internal name
level => 'top', #use for top/homepage level
extender => '~emailer', #the result: index~emailer.shtml
description => 'HTML_TMPL_DESC_home_email',
}
);
#Big Medium needs to know how to say the name of the template
#and how to describe it. Add this info to Big Medium's vocabulary.
my $lang = BigMed::Language->get_handle('en-us');
$lang->customize_lang(
'FORMAT_TMPL_HTML_home_email' => 'Homepage Email',
'HTML_TMPL_DESC_home_email' =>
'This template generates an email-friendly version of the homepage',
);
1;
We name this file HomeEmail.pm and put it into the plugins directory at this
location (you may need to create the BigMed and Plugin directories if they
do not exist).
moxiebin/plugins/modules/BigMed/Plugin/HomeEmail.pm
Plug It In
All that remains is to tell Big Medium to load our module when it looks up
its format information. To do that, we create a plugin file that flags
our module to be loaded at the appropriate time.
use strict;
use warnings;
use BigMed::Plugin;
BigMed::Plugin->add_format('BigMed::Plugin::HomeEmail');
1;
Name this script home_email.pl and put it into the plugins directory:
moxiebin/plugins/home_email.pl
Email Away
Big Medium will now automatically start building and updating a shadow
version of your homepage, named index~emailer.shtml in the same
directory as your site's homepage. The file will be available after
your next site update, or after rebuilding pages.
You'll also see that the template gets added to the template editor,
so you can make changes to your email template in the same way that
you make changes to your other templates.
