NOTE: This documentation is for Movable Type 3.2. If you are using a newer version, please see the documentation for Movable type 3.3x or Movable Type Enterprise.
One of Movable Type's most powerful traits is its flexibility to adapt to practically any weblog design or use you can imagine. For the average user, most of this flexibility comes from Movable Type's template engine.
The template engine is crucial to automating the process of publishing and is what makes a publishing system go. When a rebuild is performed, templates are merged with content to create a page that visitors can view in their browsers.
These templates are what control the design and layout of your site and what keeps that design separate from the content. Templates describe where you want to put your content and what that content should look like, using special markers (tags) that are typically mixed with another markup language such as HTML or XML.
The flexibility and power stem from the fact that with MT templates and tags, you don't need to know or understand programming code in order to customize what gets generated by the system.
There are two main ideas behind Movable Type's template system.
Movable Type template tags can be classified as two types.
Variable tags are placeholders that represent a piece of content or data. A tag of this type will be substituted with a value based on the context of its use. For instance:
<$MTEntryTitle$>
MTEntryTitle a variable tag that will be replaced with the
title of an entry.
Container tags are start and end tags (sometimes referred to as a tagset) that represent lists, contexts, and conditionals. These tags get their name because they usually contain other tags and text. For instance:
<MTEntries>
<$MTEntryTitle$>
</MTEntries>MTEntries is a container tag that lists entries. For each
entry the container lists will output the title of the entry.
There is a special type of container tag called a conditional tag. Conditional tags will only display their contents if a certain condition is true.
<MTEntryIfExtended><$MTEntryTitle$> is extended.</MTEntryIfExtended>In the example above, the entry title and the text "is extended" will only be displayed if there is content in the Extended Body field of the entry.
Container tags can also be used to create a particular context. A few examples:
The term context has been briefly mentioned already and is one you will encounter often when working with Movable Type's template tags.
Up until now, without some understanding of MT tag types and their functions in the template engine, it would have been difficult to precisely explain what is meant by the term in MT.
Context refers to the interrelated conditions of a tag's position, usage, and relationship to other tags surrounding it. The context of a tag defines its behavior, state, and even purpose during the processing of a template. Take this MT template markup for example:
<MTEntries>
<$MTEntryTitle$> <!-- in entry context. -->
</MTEntries>
<$MTEntryTitle$> <!-- ERROR! out of context. -->The first occurrence of MTEntryTitle is said to be in the
context of MTEntries. As previously discussed
MTEntries represents a list of entries that the template
engine will loop through, outputting the title with each pass. The second
occurrence in this example will generate an error because it is out of the
context of MTEntries; the template engine does not know what
entry to use to display the title.
Be aware that context is not always defined by tags. The template engine will create contexts before processing any tags. This "tagless" form of context is called an implied context, meaning it will vary depending on the template type. This is a something that will be discussed along with template types.
For those who are familiar with HTML and XML, Movable Type template tags will seem quite familiar. All template tags are enclosed within less-than and greater-than signs (sometimes referred to as angle brackets). Container end tags have a forward slash that is located after the less-than symbol, but before the tag name.
All template tag names are prefixed with "MT," to separate template tags from other markup tags. To further separate them, an optional dollar sign inside the template tag angle brackets can be added. Here is an example of a template tag:
<$MTEntryBody$>While the dollar signs are optional, it is highly recommended that they be used on all variable tags except for container tags.
<MTEntries>
<$MTEntryTitle$>
</MTEntries>This convention is used throughout the default templates and in this documentation.
The documentation says the parser cannot find the end tag if the $ is used on containers. Is this still true?
Some template tags can take attributes that modify the standard behavior of a tag. An attribute is another syntactic feature of MT tags that will be familiar to those that have previously worked with HTML and XML. Attributes are key/value pairs in the angle brackets that follow the tag name and are separated by spaces. Values are always enclosed in double or single quotes. For instance:
<MTEntries lastn="40">
<$MTEntryTitle$>
</MTEntries>In this example lastn is an attribute of the container tag
MTEntries with a value of 40. The lastn modifies the
behaviour of MTEntries by listing the last 40 entries instead
of the default, as configured in the weblog's display settings.
The template type is significant in MT, because it defines how the system is to use the template, and the context it will be given. Different types include:
Index Templates will create a single page of content from the weblog. Index Templates are commonly manifested as a list of entries; however this is not explicitly required. For instance, the default templates that ship with MT include a Style sheet template that does not list any entries -- in fact it doesn't have any MT template tags at all. (It is included as a template for convenient access.)
Index Templates have an implied context of the current weblog.
In Movable Type, an archive is the entire collection of weblog entries. Archive Templates allow for pages to be created for different views of the weblog's entries. MT supports a few date-based archives -- daily, weekly, and monthly -- in addition to individual entry and category archives. These templates are used to create multiple pages, one for each "unit" (time-period, entry or category) of the archive.
Archive Templates have an implied context of a selection of entries for
a particular time-period or category, within the current weblog. Individual
Entry Archives have an implied context of one particular entry within the
current weblog. Unlike date-based and category-based archives, a
MTEntries tag is not needed.
System templates are always created dynamically and are associated with a specific application task. The purpose of these templates vary, but are generally tied to the comments system in MT.
All system templates receive a weblog context that depends on their particular task.
Template Modules are user-defined sub-templates that contain bits of template tags, text, and other markup that can be arbitrarily included in any other template. This allows you to keep all common code in one place so modifications can be made once from one place.
See "Reusing Template Markup with Modules" for more on Template Modules.
The Templates Listing screen displays a list of all weblog templates and modules, divided by type. You can reach this screen by clicking the Templates button on the Weblog Toolbar.
1 Tabs. Tabs for accessing template lists by type.
2 Create new (type) template link. Opens a New Template Screen for the given type. This link is not available for System templates.
3 Delete Action Button. Permanently removes any checked templates from the system.
4 Actions Pulldown Menu. A control for performing any additional actions on the checked templates.
5 Template Name. The name of the template, linked to its Edit Template screen.
6 Output File. The file name and additional path information where the output will be written. Index templates tab only.
7 Dynamic Flag. The template will generate output dynamically instead of statically. Index and archive templates only.
8 Linked Flag. The template is linked to a local file.
9 Rebuild w/ Indexes Flag. The template will be included in any batch rebuild of index templates. Index templates tab only.
You want to create or edit a template for your weblog.
Use the template management screen.
Movable Type automatically installs a number of default templates when a weblog is created. These templates are fine for getting started quickly; however most users will want to customize the templates to suit their own tastes and needs.
In order to edit a template, click the Templates button in the Weblog Toolbar to get to the Templates Listing Screen. The screen is divided up using tabs, one for each template type. Find the template and click on its name to bring up the Edit Template Screen.
The Edit Template Screen has a number of fields for editing the template and its attributes. Here are all of the fields you may see on the screen. Depending on the template type some fields may not be present.
The name of the template used for identification purposes in the Templates Listing screen. The template name cannot be edited on System templates.
When editing an index template, you must specify a filename where the output of the template will be stored. For example, the output file for your Main Index template might be index.html.
The output file applies only to index templates. It can be either a path (eg. file.html) that is relative to your Local Site Path, or a full path from the root of the local filesystem (eg. /full/path/to/file.html).
When editing an index template, you have the option of automatically rebuilding the template each time you save an entry or rebuilding in batch. Generally, you should stay with the default option of rebuilding an index template automatically. There are times when you do not need to rebuild an index template automatically. For example, perhaps you are using index templates to manage primarily static content. In cases like this, you will want to turn off automatic rebuilding of static index templates, because it needlessly slows down the publishing of new entries.
If automatic rebuilds are switched off, the only way to rebuild the template will be by clicking the Rebuild action button on the Edit Template screen.
Some users will find it easier to edit the template layouts in a text editor or web page design GUI like Adobe Go Live instead of through the Movable Type browser interface. You can optionally link a Movable Type template to an external file. This allows you to edit your templates while keeping the copy that is inside Movable Type synchronized with the external file.
See "Editing a Template using an External Editor" for more on how this works.
The body of your template containing template tags and other markup such as HTML or XML.
Template tags are discussed throughout this chapter and others. See Appendix A for a complete list of the built-in tags included in MT.
Click the Save action button to store your changes in the MT database.
Creating a new template is quite similar to editing an existing one. Instead of clicking on an existing template name, click the Create a new template link just below the tabs. (You can create any type except for System templates.) This will bring up the New Template Screen for that type.
You want to create an index of your weblog's latest entries.
Create an index template using MTEntries and other tags.
Weblogs are generally organized so that their entries are in reverse chronological order with the latest post on top. Movable Type ships with a template called Main Index with just such a listing. The Main Index is essentially the homepage for the weblog.
As an index template it has an implied context of the weblog. Entries
(represented by the MTEntries tag) are selected based on
Default Weblog Display Settings unless modified with attributes.
Here is a simplified example of a main index template.
<MTEntries>
<h3><$MTEntryTitle$></h3>
<p><$MTEntryExcerpt$></p>
<p>
<a href="<$MTEntryPermalink$>">Continue reading
"<$MTEntryTitle$>"</a>
</p>
<p>Posted by <$MTEntryAuthor$> at <$MTEntryDate format="%X"$></p>
</MTEntries>For more on what these tags do see Appendix A.
You want to create pages that provide different views of a weblog's entries.
Create an archive template that is mapped to a particular archive type.
Archive Templates allows for pages to be created for different views of the weblog's entries. MT supports a few date-based archives -- daily, weekly, and monthly -- in addition to individual entry and category archives. These templates are used to create multiple pages, one for each "unit" (time-period, entry or category) of the archive.
Movable Type ships with Archive Templates for every type of archive. However, merely having archive templates in your weblog is not enough; archive pages will not be generated unless the archive type is enabled in the Archiving Mapping section of the Publishing Settings tab. These settings also enable you to control the naming of archives and create alternate archive templates. See "Controlling the Naming of Archive Pages" and "Creating an Alternate Archive Template" for more information.
The implied context for these Archive Templates is the current weblog
and a selection of entries for a particular time-period or category. Unless
instructed differently through its attributes, the MTEntries
tagset will list all entries for the category in context.
Because of the adaptive nature of the MTEntries tag we can
reuse the same markup in our discussion of the Main Index template (see "Creating a Main Index") and add an archive title.
Reusing an entry's layout is entirely at your discretion. MT allows you to
create completely unique layouts for each archive if you so choose.
<h2><$MTArchiveTitle$></h2>
<MTEntries>
<h3><$MTEntryTitle$></h3>
<p><$MTEntryExcerpt$></p>
<p>
<a href="<$MTEntryPermalink$>">Continue reading
"<$MTEntryTitle$>"</a>
</p>
<p>Posted by <$MTEntryAuthor$> at <$MTEntryDate format="%X"$></p>
</MTEntries>Tags prefixed with MTArchive, such as MTArchiveTitle from
this example, are a class of tags for displaying information about
archives. These tags used can be used in any Archive Template or in the
context of a MTArchiveList tagset.
For more on what these tags see Appendix A.
Individual Entry Archives have an implied context of one particular
entry within the current weblog. Unlike date-based and category-based
archives, a MTEntries tag is not needed. While entirely valid
when used in an Individual Archive Template, using them in that situation
does not make a lot of sense. The MTArchive tags, if they display anything
at all, will display information that can be retrieved using MTEntry
tags.
You want to create a master index of your weblog's archives.
Create an index template using MTArchiveList and related
tags.
In "Creating an Archive Template" we discussed how
to create pages that provide different views of a weblog's entries. No
matter what type of archiving you use, you are likely to need a master list
of all of your archives. Movable Type ships with such a listing as a
template named Master Archive Index. In MT, the Master Archive Index is
just an index template that uses the MTArchiveList tagset
instead of MTEntries.
Tags such as MTArchiveList are a class of tags for
displaying information about archives. These types of tags can be
identified by their MTArchive prefix.
MTArchiveList is a container tag representing a list of all
of your archive pages and can be used in any template to create a context
that all the other MTArchive tags can use.
<MTArchiveList>
<a href="<$MTArchiveLink$>"><$MTArchiveTitle$></a><br/>
</MTArchiveList>Additionally, you can use a MTEntries tag to display
information about the entries in a particular archive. For example:
<MTArchiveList>
<p>
<a href="<$MTArchiveLink$>"><$MTArchiveTitle$></a><br/>
<MTEntries>
[<$MTEntryTitle$>]<br/>
</MTEntries>
</p>
</MTArchiveList>
This will display a link to the archive page, followed by a list of entry titles.
This tag takes two attributes archive_type and
lastn. archive_type that specify the type of
archive to list with values of "Individual," "Daily," "Weekly" or
"Monthly." lastn limits the number of archives that will be
listed.
The attribute archive_type is optional. If omitted, the
listing will use the Preferred Archive Type setting. This attribute is
useful when you have selected more than one value for the weblog's Archive
Type, and you wish to list something other than your Preferred Archive
Type. For example, if you have chosen to keep both Individual
and Daily archives, and your Preferred Archive Type is
Individual, you can list your Daily archives
using this tagset:
<MTArchiveList archive_type="Daily">
...
</MTArchiveList>lastn can be used to limit the number of archives in the
list. For example, if you have 10 months worth of archives in your weblog,
and you only wish to list the last five monthly archives you could use this
tagset:
<MTArchiveList archive_type="Monthly" lastn="5">
...
</MTArchiveList>For the full list of archive-related tags see Appendix A.
You would rather use a text or web page editor to edit a template.
Link an external file to your template and edit the file.
Some users will find it easier to edit the template layouts in a text editor like BBEdit or a web page editor like Adobe Go Live instead of the Movable Type browser interface. You can optionally link a Movable Type template to an external file. This allows you to edit your templates while keeping the copy that is inside Movable Type synchronized with the external file.
In the field labeled "Link this template to a file" on the New/Edit
Template screen, enter either a full path to your external file, or a path
relative to the Local Site Path. For security purposes, the
file extension cannot be .cgi, .pm, .pl, or
.cfg. This is to avoid the potential of overwriting Movable Type
program files and corrupting the system. When you save the template the
files will be linked.
The synchronization process works in both directions. When you load a template for editing, the date of the linked file is checked, and the template is updated if the linked file date is more recent. When you save a template through the Movable Type CMS, the linked file is updated with your changes.
When you create a new template without specifying a template body, and link it to a file that already exists, the contents of that file will be pulled in to the template. If you do specify a template body, however, and the linked file already exists, that linked file will be overwritten with the template body you specified.
For instance, if you would like to maintain your Main Index template with an external editor, you would first set the linked file field to something like index.html.tmpl and click the "Save" action button. You can then edit this file externally. The next time you rebuild, Movable Type will read in the latest version of the linked file index.html.tmpl and use that as the template body. During this process it will also update the copy of the template in the Movable Type database, so that the next time it needs the template it can use the version in the database.
Another added benefit to linking a template to an external file is that you can synchronize templates across multiple weblogs. This is particularly helpful when you have multiple weblogs that require the same layout.
To do this, link all of the source weblog's templates to file. This creates external files of all the template you want to share. Then go into the other weblogs and link their templates to the files created by the first one. When you rebuild those weblogs they will now have the same templates.
You want to control the naming of files for a particular archive template.
Modify the template's Archive File Path on the Publishing Settings tab.
The Archive File Path allow you to customize the names/paths of your archive files. This allows you to define a directory structure and file naming from a weblog's archives. For each Archive Template that you use, you can define an Archive File Path in the pulldown menu to its right on the Publishing Settings tab. This pulldown includes a number of common options to choose from based on the archive type.
Also included is a "Custom" option that lets you define an Archive File Path Template. These templates are defined using a subset of the standard Movable Type template tags. The following tags can be used in Archive File Path Templates:
MTArchiveDate and MTArchiveDateEnd for
Date-based archives (Monthly, Daily, Weekly)
MTArchiveCategory and MTCategory tags for
Category archives
For instance, you may wish to file away posts in your archives based on their category. So all entries assigned to the category "Books" would get placed into a directory called books/. To implement this with an Archive File Path Template, you would use the following markup for your Individual Entry archives:
<$MTEntryCategory dirify="1"$>/<$MTEntryID pad="1"$>.htmlThis template will output file names like:
books/000007.html
books/000040.html
books/000072.htmlWhen using Archive File Path Templates, you must append the file extension that you wish to use for your archive files. The file extension that you specify in your settings will not be used.
I assume this is now gone, however a pulldown menu option should exist.
(Note that users of previous Movable Type versions can choose backward-compatible filenames in Weblog Config.)
We should mention why not. Jay?
You want to create a secondary archive template for use in your weblog.
Create a new Archive Template and map it to an archive type from the Publishing Settings tab.
Movable Type allows you to assign multiple templates to an archive type. This allows you to output archived content with different layouts or formats if necessary. For instance, you may want to generate a syndication feed for each category in your weblog.
Begin by creating a new Archive Template. MT uses very descriptive functional names.
To create the archive mapping, go into Settings and then the Publishing tab. Click the "Create New Archive Mapping" link under Archive Mapping. This will display controls for creating the mapping.
Select the archive type and the name of the alternative archive template you just created from the two pulldown menus. Click the Add button to create the mapping in the system.
You will probably want to change the filename of the template you just mapped to avoid it writing over the existing template. (See "Controlling the Naming of Archive Pages".) When you rebuild your weblog archive pages, they will be generated with this template in addition to any other archive templates enabled in the system.
You want to reuse a piece of markup or text.
Create a template module for reuse where necessary.
Template modules are found in your blog's template listing screen under the Modules tab. From there you can manage all existing template modules and create new ones.
Template Modules allows you to keep all common markup in one area so that modifications can be made from one place. Modules can contain bits of template tags, text, and other markup that are never directly output as a page. Instead they can be arbitrarily included into any other template, as many times as needed.
For instance, you could create a template module named "Copyright" as such:
<p>Copyright © 2002-2005. All Rights Reserved.</p>This module is quite simple and could have easily contained any amount
of MT template tags or even other modules if appropriate. With the
"Copyright" module saved you could add template markup to include it in
every one of the weblog's templates. To include a module use
MTInclude with the module attribute.
<$MTInclude module="Copyright"$>With this template tag in place, the contents of the Copyright module would be inserted at this point. If our module contained MT template markup, it would have been processed as if it were part of the template in which it was included.
You want to display data about your weblog in a template.
Use the template tags prefixed with MTBlog.
Movable Type includes a collection of variable tags for displaying information about a weblog in templates. These tags are prefixed with MTBlog. The following sample layout publishes some information about a weblog and the number of entries and comments.
<div>
<$MTBlogName$><br/>
<$MTBlogURL$><br/>
<$MTBlogDescription$><br/>
Entries: <$MTBlogEntryCount$>
Comments: <$MTBlogCommentCoount$>
</div>For the full list of weblog-related tags see Appendix A.
You want to create a calendar layout in your template.
Use the template tags prefixed with MTCalendar.
Movable Type includes a collection of template tags prefixed with MTCalendar; these can be used for creating calendar layouts that serve either navigational or display purposes. MTCalendar tags are sufficiently generic to create calendars in many different formats; however, HTML tables are the most common,
MTCalendar is a container tag representing a calendar month
that lists a single calendar "cell" in the calendar display. A calendar
cell is either a day of the month or a blank; this is used to represent a
day in a different month.
This tag takes an optional attribute month, which, if
present, specifies the desired calendar month and year. If the value of
this attribute is the string this, the calendar will be
created in the surrounding date context; this means that, for example, in
an archive template, you can use:
<MTCalendar month="this">
...
</MTCalendar>This represents the month of the archive currently being viewed. This
will work for Individual, Daily,
Weekly, and Monthly archives, but not for
Category archives.
If the value of the month attribute is last,
the calendar will be created for the previous month, relative to the
current date.
If you'd like to create a calendar for a specific month, you can use the
month attribute to specify the exact month and year in
YYYYMM format. For instance to display the calendar for April
2005 the month attribute would have a value of "200504."
If the month attribute is not provided, the calendar will
display the current month.
If you would like to only display entries from a certain category, you
can optionally specify the category attribute, giving it the
category label.
<MTCalendar month="200504" category="Foo">
...
</MTCalendar>The numeric day of the month for the cell.
A conditional tag that will display its contents if there are any entries for this day in the weblog.
A conditional tag that will display its contents if there aren't entries for this day in the weblog. This tag predates to introduction of MTElse that could be used with MTCalendarIfEntries to replace this tag.
A conditional tag that will display its contents if the current calendar cell is for a day in another month.
The contents of this tagset will be displayed before a calendar week is started.
The contents of this tagset will be displayed after a calendar week is ended.
Prior to version 3.2, a calendar display was included in the Main Index template of the default template set. This markup has since been removed to speed up rebuilding times.
The following is the layout that was included in the default templates but with the styles updated for Movable Type 3.2 (thanks to Arvind Satyanarayan).
<h2 class="module-header"><$MTDate format="%B %Y"$></h2>
<div class="module-content">
<table summary="Monthly calendar with links to each day's posts">
<tr>
<th abbr="Sunday">Sun</th>
<th abbr="Monday">Mon</th>
<th abbr="Tuesday">Tue</th>
<th abbr="Wednesday">Wed</th>
<th abbr="Thursday">Thu</th>
<th abbr="Friday">Fri</th>
<th abbr="Saturday">Sat</th>
</tr>
<MTCalendar>
<MTCalendarWeekHeader>
<tr>
</MTCalendarWeekHeader>
<td>
<MTCalendarIfEntries>
<MTEntries lastn="1">
<a href="<$MTEntryPermalink$>"><$MTCalendarDay$></a>
</MTEntries>
</MTCalendarIfEntries>
<MTCalendarIfNoEntries>
<$MTCalendarDay$>
</MTCalendarIfNoEntries>
<MTCalendarIfBlank> </MTCalendarIfBlank>
</td>
<MTCalendarWeekFooter>
</tr>
</MTCalendarWeekFooter>
</MTCalendar>
</table>
</div>
</div>As you can see, calendar layouts get complex rather quickly. The computation of the calendar display can significantly extend the processing time involved in rebuilding pages. It is generally recommended that these tags be applied judiciously, if at all, to your templates.
For the full list and descriptions of all calendar tags see Appendix A.
You want to publish some content when a conditional is false.
Use the MTElse tag inside of the container tag.
As discussed in the introduction to this chapter, conditionals are a
special form of container tags that will display their contents only if a
certain condition is true. Movable Type includes MTElse, a
very useful tag that can be used with conditional tags. Inside of any
conditional, this tag will display its contents if the conditional is
false. This template markup demonstrates its use.
<MTEntryIfExtended>
<p>TRUE</p>
<MTElse>
<p>FALSE</p>
</MTElse>
</MTEntryIfExtended>Used in the context of an entry, "TRUE" would be published if the Extended Body field contained any content. "FALSE" would be published if it did not.
You want to modify the output of a tag.
Use a global filter on the tag.
Global filters are special attributes that can be applied to any tag to
transform its output before publishing. For instance if you wanted to
display entry titles in all capital letters you could apply the
upper_case global filter like so:
<$MTEntryTitle upper_case="1"$>Multiple filters may be used and follow an internal system-designated order for processing, not the order in which they appear.
For a list and description of all built-in global filters see Appendix B and Appendix A.
You want to format the timestamp of a date tag.
Use the format attribute with the Date Tag Format
codes.
Movable Type provides added functionality to tags that handle date and
time information. These tags will recognize a format attribute
that defines the explicit date/time format to output. These formats are
based on the strftime utility found on all Unix systems. A
complete listing of the codes can be found in Appendix C.
For instance, if you were to insert this template markup into the context of an entry:
<$MTEntryDate format="%B %e, %Y %l:%M %p"$>
<$MTEntryDate format="%A"$>
<$MTEntryDate format="%H:%m"$>Although the MTEntryDate tag will always retrieve the same
value, it will be formatted in three different ways. The output of these
tags would look something like:
April 22, 2005 3:26 PM
Friday
15:26Typically these tags have "date" in their name, however you should
consult the Appendix A about
whether or not the format attribute applies to a given
tag.
