Caveat Lector

This is entirely out of sequence, but Loren asked, so I might as well share.

An issue noted by many Movable Type users is the server overhead of putting together the comments screen anew every time someone clicks on a Comments link. One way to lessen the burden is to include comments (rather than a comments link) directly into your archive pages. If you use Individual archive pages (as Loren does), it’s even possible to include the commenting form as well.

First, you need to figure out where to put the code in the template. Look for the end-tag for the placeholder </MTEntries>. If your template is like most, there is a div end-tag right above it that is probably the end of each blog entry. Just above that is where you want your comments and trackbacks.

Here’s a copy of the comment-and-trackback inclusion template that I use for the archive pages on Ravings. It’s a little rough-and-ready (all those grotty evil <br /> tags!), but it should work.

<div class="comments">
<h3 class="comments-head">Comments</h3>

<MTComments>
<div class="comments-body">
<$MTCommentBody$>
<p class="comments-post">Posted by <$MTCommentAuthorLink spam_protect="1"$> <$MTCommentDate$></p>
</div>
</MTComments>

<h3 class="comments-head">Pings</h3>
<p class="trackback-url">TrackBack URL for this entry: <a href="<$MTEntryTrackbackLink$>"><$MTEntryTrackbackLink$></a> </p>

<MTPings>
<div class="trackback-body" id="p<$MTPingID$>"></a> <p class="trackback-post"><a href="<$MTPingURL$>"><$MTPingTitle$></a><br />
<b>Excerpt:</b> <$MTPingExcerpt$><br />
<b>Weblog:</b> <$MTPingBlogName$><br />
<b>Tracked:</b> <$MTPingDate$></p>
</div>
</MTPings>

</div>

I hope you don’t mind if I don’t comment exhaustively on this until much later. I had enough trouble just marking it up!

I should not have to write this post. It’s just that the documentation for dates in Movable Type is—okay, it’s just plain organized wrong. I hope this will be fixed in an upcoming release.

Date- and time-related placeholders (<MTEntryDate>, <MTCommentDate>, <MTCommentPreviewDate>, <MTArchiveDate>, <MTArchiveDateEnd>, <MTPingDate>, and <MTDate>) all have a format attribute whose value is a concatenation of incomprehensible codes starting with % that represent various parts of a date and time.

If you’re lucky, you can use the two fully-elaborated codes and save yourself a lot of pain. %x gives you the date, in the form “September 6, 2002”. %X gives you the time, in the form “4:31 PM”. If these work for you, for heaven’s sake use them!

Otherwise, read on…

Movable Type’s documentation organizes all these codes alphabetically by code, which is great for geeks, not so good for everybody else. Here’s the list organized by unit of time, small units first, the way $DEITY intended:

Second: %S

Minute: %M

Hour:

• 24-hour, two digits: %k
• 12-hour, always two digits: %I
• 12-hour, one or two digits: %l

AM or PM: %p

Weekday name:

• In full: %A
• Abbreviated: %a

Day of month:

• Always two digits: %d
• One or two digits: %e

Day of year: %j

Month:

• In full: %B
• Abbreviated: %b

Year:

• Two-digit: %y
• Four-digit: %Y

Putting it all together: To get a date header like Caveat Lector’s—well, first you have to hack Movable Type itself to produce Latin month and weekday names. Not recommended, but I’ll tell you how if you ask.

But let’s pretend that I am a normal English-language blogger using English-language dates. What I’m using is the full weekday name, a comma, the one- or two-digit day of the month, the full month name, and the four-digit year. That works out to <MTEntryDate format="%A, %e %B %Y">. Note that you have to include any punctuation (such as my comma) and spaces you want.

Whereas the weekly-archive links in my blogroll use the abbreviated month, the one- or two-digit day of the month, and the four-digit year. (And the month names are in English, but you don’t need to know how I did that.) That’s <MTArchiveDate format="%b %e %Y">.

See? Not so bad. Okay, okay, bad but manageable.

If you’re scared of your Movable Type templates, you aren’t alone. I hear that pretty regularly. So it only makes sense that experimenting with the templates that make up your live blog is Not To Be Thought Of until you’ve built up a little more confidence.

Fear not. It’s easy to make yourself a new template to use as a sandbox to play in. In fact, before we go any further I strongly recommend you do this, because we’re going to build a template from scratch, something you do not want to do on your main blog page.

Here’s how.

Click the Templates button on the left-hand button bar. (No left-hand button bar? You’re in the main menu. Click on your blog’s name.) You should see a list of templates, the main ones at top. Click on “Create new index template.”

You should get the same template editing menu you’re already used to from looking at your other templates, only blank. Name your template (how about “Sandbox”?) and give it a file to write to (try “sandbox.html”). Leave the “rebuild when rebuilding indexes” checkbox checked, and do not put anything in the “Link this template to a file” box.

Click “save,” and go ahead and rebuild (choose the “indexes only” rebuild option). That’s it. You’re done.

Where is the page that this (currently empty) template creates? In the same folder as your main blog page. If your main blog page is http://blog.example.com/index.html, your sandbox page is http://blog.example.com/sandbox.html.

What to put in the template… we’ll get into in upcoming posts.

I promised to talk about why I don’t like the placeholder <MTEntryPermalink>, and what I think should replace it. Let’s be clear: this is a markup-geek objection, and if you are not a markup geek you probably won’t care.

Off we go, then…

<MTEntryPermalink> is a concatenation of <MTEntryLink>, a pound sign, and <MTEntryID>. Comes out to something like http://blog.example.com/archive/2003/04/28.htm#000512. Fine, as far as it goes. Where’s the problem?

The problem is that in any flavor of HTML, X- or otherwise, you cannot use an unadorned number as the value of an id attribute. All id attributes must begin with a letter. I talked about this during AKMA’s first markover, so I won’t repeat myself.

If you want your permalinks to point to id attributes rather than a name attributes, you cannot use <MTEntryPermalink> in your template. It’s that simple.

This is what I recommend you do. Keep in mind that if you have a long-running blog, this will break your current permalinks, so proceed with caution.

On your archive pages, you probably surround each blog entry with a div. The default MT templates use <div class="blogbody">, which is fine. Add an id attribute, thus:

<div class="blogbody" id="e<MTEntryID pad="1">">

(The pad placeholder adds a bunch of extra zeroes to the beginning, just for neatness. It isn’t strictly necessary, but if you use it on <MTEntryID> in one place, use it on all other <MTEntryID> placeholders in all your templates as well.)

Note the letter at the beginning of the id attribute value. Can be any letter you like; I use e-for-entry.

Then, whenever you would otherwise use an a element with <MTEntryPermalink>, use this instead:

<a href="<MTEntryLink>#e<MTEntryID pad="1">"> (whatever you want as the text of the link)</a>

Again, it’s a markup-geek thing. If you’re setting up a new blog, however, keep it in mind.

At last and alack, the promised entry on the <MTEntries> placeholder. A good thing to spend an entire entry on: not only is this a crucially important placeholder, its usage ties together most of what I’ve been on about this entire series so far.

The <MTEntries> placeholder represents a list of blog entries, in the abstract. To get concrete, you need to put something inside <MTEntries>. For example, the default MovableType blog template (as of version 2.63) includes a list of the latest ten entries by title in the sidebar. The template code for this is (stolen straight from said template):

<MTEntries lastn="10">
<a href="<$MTEntryPermalink$>"> <$MTEntryTitle$></a><br />
</MTEntries>

See? I bet you can figure out what’s going on there without my saying a word.

(I’m color-coding template snippets to make it easier to tell MovableType placeholders from HTML tags. I hope it helps. Incidentally, I do not recommend that you lift this code-snippet as is. I have issues with <MTPermalink> which I will discuss in a later entry. If you’re already using it, leave it be for now. Said later entry will discuss what to replace it with and why. Plus, I hate the use of the <br /> tag here. Better ways to do this.)

Note all the placeholders starting with <MTEntry>. They’re context-dependent. You can use them inside <MTEntries> and (for your information) inside <MTSearchResults>—and nowhere else. Use them anywhere else and your template won’t work.

<MTEntries> all by itself means the entire list of blog entries for your blog. It fits inside two other placeholders, however, to represent a more restricted list of entries:

• <MTArchiveList> is a list of all your archive types. If you put <MTEntries> inside it, you access a list of the entries for each archive type. If you use Individual, Monthly, and Category archives, for example, you could use this combination to list the last ten entries ror each of these archive types.
• <MTCategories> is a list of all your categories. If you put <MTEntries> inside it, you access a list of entries for each category.

The other way to restrict <MTEntries> is with attributes. You can load as many attributes as you like onto a single placeholder; they all add up.

The example above already snuck one attribute in on you: lastn restricts the entry-list to the last however-many entries you specify. Here are the important (in my no-doubt-biased view) other ones:

• category restricts the list to a specific category. The difference between this and putting <MTEntries> inside <MTCategories> is that this limits the list to the single category you specify, whereas <MTCategories> cycles through every category you have.
• days limits the list to entries from the last however-many days you specify.
• sort-order specifies whether to list the first or last entries first. The value ascend starts at the beginning; descend starts at the end. For a newest-posts-first ordering, you want descend.

You may also want to be aware of the following global attributes, which seem to me particularly useful on <MTEntries>:

• filters lets you filter your entries through various Perl text filters. Nifty, if you happen to have those filters available (ask your webhost).
• upper_case and lower_case do what they say they do. I prefer to do this with CSS (View Source and look at my entry titles to see what I mean), but unfortunately not all browsers do it properly, so this is a reasonable alternative.

There. Now you know your way around the most important part of your blog template—the entries.

You have gathered by now, I hope, that some Movable Type placeholders play chameleon, changing their stripes depending on what’s surrounding them.

For some placeholders, there’s another way to tweak what they do: adding one or more attributes to them.

If you do HTML at all, you understand the idea of an attribute already. In the quite feasible HTML tag <h2 class="subtitle">, there is an attribute class with the value subtitle. Attributes typically describe and/or limit what they’re attached to.

Movable Type placeholder attributes work the same way HTML attributes do, both in syntax and intent. Hooray for transferable knowledge.

Some attributes can (theoretically, at least; in the real world some of them won’t make sense everywhere) be used on any Movable Type placeholder. The Movable Type documentation calls these “Global Tag Attributes” and does such a fine job of describing them that I don’t feel the need to recap.

Most attributes, though, are specific to specific placeholders. The <MTCalendar> placeholder, for example, has a month attribute that lets you specify which month you want to display. Acceptable values are “this” for this month, “last” for last month, or a six-digit number containing the four-digit year and two-digit month, like 200304 for April 2003.

So if I have such an undying love for this month that I want its calendar somewhere on all my blog pages, I would start the calendar in my template with <MTCalendar month="200304">. Simple as that. (Then I’d have to put in a bunch of other calendar placeholders, which are not simple at all… but I digress.)

This may seem a silly thing to say, but here I go anyway: Don’t use Movable Type attributes on HTML tags, and don’t use HTML attributes on Movable Type placeholders. Won’t work. (This is another reason I wish the syntax for Movable Type placeholders weren’t so HTML-ish. Yes, I know I just said “hooray for transferable knowledge,” but there’s also a confusion cost.)

That’s it. Easy lesson. Next up: the weird and wonderful <MTEntries> placeholder, without which no blog template is complete.

Here is a list of all container placeholders in Movable Type (version 2.63). For placeholders that have them, I have also listed contained placeholders (sometimes by reference) and context-dependent placeholders, along with their meaning in context.

You don’t need to memorize these lists; they’re purely for reference. Hey, knock yourself out if you want to, though; should take you less time than the two days it’s taken me to compile them!

Remember, just for review: “Contained” placeholders will not work outside their container; your template will refuse to rebuild. “Context-dependent” placeholders change meaning inside particular containers.

First, though, I’ll list out the conditional containers, the ones that only do something if some other condition is met. These never have contained or context-dependent placeholders, so they’re easiest. Note that all of these are contained placeholders themselves; you can’t use them just anywhere. Generally the context is evident from the title or description. If it isn’t, that probably means you don’t use the context and so can ignore its contained placeholders.

• <MTBlogIfCCLicence>: This tag only takes effect if you have assigned a Creative Commons license to your blog.
• <MTEntryIfExtended>: Takes effect if entry has an extended section.
• <MTEntryIfAllowComments>: Takes effect if entry has commenting enabled.
• <MTEntryIfCommentsOpen>: Takes effect if entry comments are still open.
• <MTEntryIfAllowPings>: Takes effect if entry has TrackBack enabled.
• <MTCalendarIfBlank>: Takes effect if this cell in the calendar has no date (as at the beginning or end of a month).
• <MTCalendarIfEntries>: Takes effect if this date in the calendar has blog entries associated with it.
• <MTCalendarIfNoEntries>: Takes effect if this date in the calendar does not have entries associated with it.
• <MTCalendarIfToday>: Takes effect if this date in the calendar happens to be today’s.
• <MTDateHeader>: Takes effect if a given post is the first post of the day.
• <MTDateFooter>: Takes effect if a given post is the last post of the day.
• <MTEntriesHeader>: Takes effect if a given post is the first on the page.
• <MTEntriesFooter>: Takes effect if a given post is the last on the page.
• <MTNoSearchResults>: Takes effect if a search query turns up no results.
• <MTNoSearch>: Takes effect if someone presses the search button without entering a search.
• <MTBlogResultHeader>: If your Movable Type search gizmo searches multiple weblogs (most don’t!), it groups the results by weblog. This placeholder takes effect on the first search result for any given weblog. (The documentation suggests putting the weblog’s name, <MTBlogName>, inside this placeholder, which seems eminently reasonable to me.)

Right. Now for the other containers. I have probably missed some context-dependent placeholders; my brain got to hurting after a while. If you see what I didn’t, let me know and I’ll fix the omission and (of course) credit you.

• <MTBlogs>: A list of all weblogs dependent on this installation of Movable Type. (For example, one for Yarinareth’s MT installation would include Ravings and Shark Tank as well as CavLec.)

  Contained placeholders: None.

  Context-dependent placeholders: Any that begin with <MTBlog>, e.g. <MTBlogID>. Inside this container, they repeat for all blogs in the system (so <MTBlogID> would list the IDs for all blogs). Outside it, they refer only to your specific blog.

• <MTEntries>: A list of blog entries. Exactly which blog entries it lists is controlled by attributes on the placeholder. (I’m going to do a whole post on this placeholder eventually. It’s very powerful and very confusing.)

  Contained placeholders: Any beginning with <MTEntry> or <MTEntries>, e.g. <MTEntryTitle>.

  Context-dependent placeholders: <MTComments> inside this placeholder lists comments on a given entry only. Outside it, it lists comments from the entire weblog. Also note that <MTEntries> is itself context-dependent. More on these things in another post.

• <MTCategories>: A list of blog categories.

  Contained placeholders: None.

  Context-dependent placeholders: Any beginning with <MTCategory>, e.g. <MTCategoryTitle>. Inside this container, they repeat for all categories in the blog. Inside <MTEntries>, they output data only for the categories that apply to a given blog entry.

• <MTComments>: A list of comments. Precisely which comments depends on which container this placeholder is inside.

  Contained placeholders: Any beginning with <MTComment>.

• <MTArchiveList>: A list of archive pages. You can choose the archive type (daily, weekly, category, etc).

  Contained placeholders: Anything starting with <MTArchive>.

  Context-dependent placeholders: <MTEntries> lists only entries relevant to the archive type given; if no archive type is given, lists only entries in the “preferred” archive type you set on the Archiving page in Configuration.

• <MTPings>: A list of TrackBacks received.

  Contained placeholders: Anything beginning with <MTPing>.

• <MTPingsSent>: A list of TrackBacks sent.

  Contained placeholders: <MTPingsSentURL>, a list of the URLs to which TrackBacks have been sent.

• <MTSearchResults>: A list of results for a search of the blog via the Movable Type search box.

  Contained placeholders: Any beginning with <MTSearchResult>, as well as <MTBlogResultHeader, <MTEntryEditLink>, and <MTSearchString>

• <MTGoogleSearch>: A list of search results obtained via Movable Type’s linkage with the Google Search API. (If that made no sense, don’t worry; you don’t need this placeholder.)

  Contained placeholders: <MTGoogleSearchResult>.

Whew. That’s quite a list. I hope it proves useful to someone.

Next up: Placeholder attributes.

Some Movable Type placeholders go anywhere, any time. Your <MTBlogEntryCount> will be the same no matter where you plunk it down on your page; it is governed by how much you post, not where you stick the information about how much you post.

These placeholders are relatively easy to understand and deal with, being (vis-a-vis the template) context-free. Unfortunately, not all placeholders are like that. Those that aren’t fall into three types:

1. Some placeholders establish a context, within which other placeholders do certain things. The Movable Type documentation calls these “container tags,” but I am going to continue my convention of calling MT-specific constructs “placeholders,” reserving the word “tag” for HTML constructs. These, then, are “container placeholders.”
2. Some placeholders are specifically designed to work only within the context of a specific container placeholder. Call them “contained” placeholders, for the sake of argument.
3. Still other placeholders change their behavior based on the context established by container placeholders. I’ll call these “context-dependent placeholders.”

A quick example, just for (say it with me) context: The <MTEntryTitle> placeholder stands for the title of a given blog entry. It is contained, only usable within <MTEntries>, which is a container placeholder standing for generic blog entries. When you think about it, of course, this makes sense: an entry title has no meaning outside blog entries.

Container placeholders, just for your information, get used for two kinds of blog parts: parts that repeat with different data, and parts that may or may not be there. Blog entries, for example, repeat: a single blog page may (and usually does) contain multiple entries, all with the same structure and markup despite differing content.

Comment-related text or links may or may not be there: if, for example, some of your entries allow comments and others don’t, you may want to show a comments link if you’re allowing comments but suppress the link if you’re not. You can do that, but you have to put the template code for the comments link inside a container that tells MT “if I allow comments to this post, do this; otherwise, not.”

So how do you know if a given placeholder you’re looking at is a container? Look for an end-placeholder, which will have a slash after the < just as an end-tag in HTML does. If you see <MTEntries>, somewhere a little later you will also see </MTEntries>. Container placeholders must have end-tags; if you do not close them off, your template will not work properly and Movable Type will hand you an obscure error when you try to rebuild.

A cheat specifically for containers representing repeated parts of a page: is the placeholder name plural? <MTEntries> is a container; <MTEntryTitle> is not. This isn’t universal; <MTArchiveList> is a container of this type, for example. Still, worth checking.

A cheat specifically for containers representing optional parts of a page: look for the word “If” in the placeholder name. Optional code for comments, for example, would be placed inside the container <MTEntryIfAllowComments> </MTEntryIfAllowComments>.

If you still aren’t sure, look for the placeholder in the TEMPLATE TAGS section of the MT help files; containers are clearly stated to be such.

Movable Type container placeholders generally have contained placeholders, as I mentioned: placeholders that go inside one specific container and will not work anywhere else. If you put <MTEntryTitle> outside <MTEntries>, for example, your blog will not rebuild properly; the error you get should tell you which placeholder has been orphaned in your template. The fix? Add the container to the template, or check that the container is closed off in the right place, after the contained placeholder that isn’t working right.

If you know the name of the container placeholder, its contained placeholders generally aren’t hard to spot. Remember how most container placeholders are plural? The names of their contained placeholders almost always begin with the singular. You can be dead sure that whatever <MTEntryFoo> is (I just made it up; it isn’t a real placeholder, so don’t use it!), it is a contained placeholder within <MTEntries>.

Just when you thought this couldn’t get any more complicated… some placeholders behave a little differently depending on the container they’re in. Context-dependent placeholders, remember them? They will be the topic of the next post. Before I’m done, I’ll make you a list of container placeholders and meaning-shifting placeholders, just for reference.

Some of Movable Type’s template placeholders have their values set in the Weblog Config pages. I thought I’d run those down for you, because the connections are nowhere explicitly made (though they are alluded to) in the Movable Type help files, so if you run into a placeholder problem it’s hard to know what to do about it.

You can follow along by clicking on the Weblog Config button in the left-hand menu bar.

Starting with the Core Configuration page:

• <MTBlogName> is set in the “Weblog name…” box at the top.

• <MTBlogURL> is set in the “Site URL” box.

  (This box also controls <MTBlogRelativeURL>, but the chances that you will ever use that are minimal so I don’t intend to explain it. By the same token, the “Local site path” box governs <MTBlogSitePath>, but who cares? Not you.)

• <MTArchiveURL> is set in the “Archive URL” box.

  This is the page which the “Master Archive Index” template creates, incidentally. If you mean to have your archives in a separate directory or subdirectory from your main page (I do this, for neatness, but it isn’t necessary), this is the one case when you must mess with the “Output file” box on the template page. Change the default (which I believe is “archive.html”) to the name of the directory plus a slash and “index.html.”

  If, for example, you create a directory called “archive” inside your main blog directory (as CavLec has done), you need to put archive/index.html inside the “Output file” box on the “Master Archive Index” template page. (Whew!)

On the Preferences page:

• <MTBlogDescription> is set in the “Description” box.

That’s about it. If I’ve missed any, let me know.

Next up: Building a template from scratch for a skeleton blog. Or something like that.

Movable Type’s templates are something like the form letters or mail-merges you can create in your word-processor. Very, very complicated form letters, with lots of spaces for pieces of your blog that vary from day to day or post to post. When you look at a Movable Type template, you are seeing three basic elements:

1. text on your blog page that never changes (e.g. the title of your search box or blogroll, if you have these things)
2. HTML markup that ends up on your blog page, behind the scenes (find the View Source item in your web browser’s menus to see it)
3. Movable Type placeholders for elements of your blog page that change (e.g. dates and posts)

Unfortunately, it can be very difficult to tell HTML markup from Movable Type placeholders. If you get lost, it’s not just you—it’s confusing. I lose my place in templates all the time. Honestly, I do. A moderately complex template looks like one great big angle-bracketty mess. So give yourself time and patience to sort it all out.

I’m going to assume here that you understand the basics of HTML tagging—you know what angle brackets are for, and you can tell a start-tag from an end-tag. If not, my advice to you is to choose View Source in your browser on a blog you know has clean markup (I recommend Dive Into Mark, mostly to annoy him) and compare what you see to what appears on the page. You’ll soon figure out what’s what by osmosis.

How do you tell an HTML tag, which Movable Type will use as-is on your blog page, from a Movable Type placeholder? A couple of ways:

• Look for the MT at the beginning of the name, so: <MTEntryDate>. No HTML tagname starts with the letters “MT,” and I believe all the Movable Type placeholders do.
• Look for dollar signs just inside the wedges, so: <$MTBlogName$>. Only MT placeholders can have dollar signs in those places. The dollar signs are always optional, so you can’t count on them as your sole discriminator, but they are helpful when present.

What’s really ugly is that you can nest a Movable Type placeholder inside an HTML tag. Talk about your angle-bracketty messes! This typically happens inside an HTML attribute value. Take, for example, the permalink, which often shows up as the value of a href because it’s a link.

For the sake of argument, let’s use “Permalink” as the text of the permalink (as I do), rather than the time or date of posting as many other blogs do. The permalink part of a Movable Type template would then look like this:

<a href="<MTEntryPermalink>">Permalink</a>

Movable Type figures out what the URL for the permalink is and substitutes it into the page where the placeholder <MTEntryPermalink> is. The resulting HTML on the blog page is something like this (minus the line-break I am putting in for readability):

<a href="http://blog.example.com/2003_04.htm#000581">
Permalink</a>

and people surfing the blog can click on the word “Permalink” and go to the entry in the archives.

Mmmmmm… angle brackets. If you survived this example, you’ll be fine. Even if you only kinda-sorta get it—you’ll be fine.

Newbie hitch: The single commonest mistake I make while editing my templates is leaving out (or accidentally deleting) end-quotes and close-angle-brackets. If you just edited your template and great huge chunks of your page are suddenly being swallowed into the ether, this is probably why. Check what you edited for missing quotes and brackets.

Next up: Hmm. I’m not sure. Maybe MT placeholders related to the blog page as a whole? If you have other ideas, let me know.