Help!

Or search support forum

What's Global Moxie?

Global Moxie specializes in mobile design strategy and user experience for a multiscreen world. We offer consulting services, training, and product-invention workshops to help creative organizations build tapworthy mobile apps and effective websites. We're based in Brooklyn, NY. Learn more.

On Shelves

Books by Josh Clark

Tapworthy: Designing Great iPhone Apps

Best iPhone Apps: The Guide for Discriminating Downloaders

iWork ’09: The Mising Manual

Moxiemail

Enter your e-mail to receive occasional updates:

How do I add a new page type with its own custom template?

Important: Sales, service, and support of Big Medium are no longer offered. More details.

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. (For Big Medium installations installed prior to v2.0.5, this page will be named index~emailer.shtml even when the installation is updated to later versions.)

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.

Download Big Medium
Try it free for 30 days, or buy to unlock.

Listen Up

“I listen to what Josh Clark has to say.”
—Matt Legend Gemmell, developer, Instinctive Code

“Tapworthy is a great iPhone development book.”
—Joe Hewitt, creator of the Facebook iPhone app

“I snagged a copy of Josh Clark’s Tapworthy. Mmmm... that’s good interface.
—Boon Sheridan

More praise for Tapworthy