Not a developer? Go to MovableType.com

MovableType.org
Documentation
Home / Documentation / Appendices Appendix: Template Tags

Entries

A block tag which iterates over a list of published entries from a blog and outputs a selection of entries that are appropriate for the context used and the template being published.

The <mt:Entries> tag is one of the most basic tags you’ll use in working with Movable Type. Put simply, you open and close the <mt:Entries> and </mt:Entries> tags, and in between, Movable Type will loop through all of your entries, displaying the information you’ve chosen in the format you desire.

<mt:Entries>
    <$mt:EntryTitle$>
    <$mt:EntryBody$>
</mt:Entries>

Nearly every template uses <mt:Entries> in one way or another because this tag is so powerful. You can add in attributes to specify exactly which entries to show on your page. Attributes can be used in combination to sort, select, and filter entries exactly as desired. Be sure to check out the examples.

The default behavior is set according to the “Entry Listing Default” and “Entry Order” preferences in the Entry Settings. The attributes days, lastn, and sort_order attributes override their corresponding settings in the blog’s General settings menu.

Used without any attributes, <mt:Entries> will output entries based upon the context in which it is used:

  • Index Template: recent entries as specified by the “Entry Listing Default” preference in the Entry Settings
  • Archive Templates: all the entries in context of the template’s archive mapping:
    • monthly: all entries for the month in context
    • category: recent entries in a category
    • author: recent entries by a particular author
    • category-monthly: all entries in a category published in the same month

Note: author and category archive mappings are limited to the value set for “Entry Listing Default” preference in the Entry Settings. Without this default, these archives could take progressively longer and longer to publish. You can override this default with the lastn attribute.

The <mt:Entries> tag can be placed in custom modules, index templates and widgets to select content in many different ways.

The output <mt:Entries> can be affected by mt:Entry tag attributes and template tag modifiers.

Beware that the ordered combination of attributes and modifiers can affect the output of <mt:Entries>.

Attributes

All <mt:Entries> attributes are optional. The most common attributes are:

MultiBlog attributes

author

Accepts an author’s username to filter entry selection. (The username is the one you log in with, not the fancy Display Name if you’ve set that in your profile.)

<mt:Entries author="melody">

Tip: To dynamically apply the author username use variable interpolation with the mt:EntryAuthorUsername tag (when in entry context):

<$mt:EntryAuthorUsername setvar="entry_author_username"$>
<mt:Entries author="$entry_author_username">
  <li><a href="<$mt:EntryPermalink$>"><$mt:EntryTitle$></a></li>
</mt:Entries>

category

This attribute allows you to filter the entries based on category assignment. The simple case is to filter for a single category, where the full category name is specified:

<mt:Entries category="Featured">

Multiple categories with the same name can be differentiated using their parent category names to be more explicit:

<mt:Entries category="News/Featured">

or

<mt:Entries category="Projects/Featured">

Advanced Boolean logic is supported in category and tag attributes (AND, OR, NOT, parenthetical grouping) to include or exclude categories:

<mt:Entries category="(Family OR Pets) AND Featured">

or

<mt:Entries category="((Cats AND Dogs) OR General) AND NOT Private">

or

<mt:Entries category="NOT Family">

categories

Alias of category.

days

Filters all posts less than N days old (the date when the page is published). N is a positive number, typically an integer.

The days attribute should be used separately from other attributes. If used with another attribute, days is ignored.

To display all entries with a publish date in the last 10 days, use this:

<mt:Entries days="10">

Set a number of days to be the default behavior for the <mt:Entries> tag in the “Entry Listing Default” preference in the Entry Settings

Additionally, the days attribute can be used in an obscure way with a very small value that can be set to “0.0000000000001” to force only future (non-today) entries to publish, as explained by Maarten Schenk of Movable Tips. (Setting the value to “0” does not have the same effect.)

field:basename

Permits filtering entries based on a custom field defined (custom fields are part of the Commercial Pack in MT 4.0 and 4.1, and are built in to MT Pro from version 4.2 on.).

Select the last 5 entries that have a check box custom field with a basename of “subscribe” which is checked:

<mt:Entries field:subscribe="1" sort_by="authored_on" sort_order="descend" limit="5">

glue

A string that is output between published entries. Use it to comma-separate items, to add spaces or tabs, or to do even more complicated things.

Output a comma-separated list of entry ids (i.e. 3,2,1):

<mt:Entries glue=","><$mt:EntryID$></mt:Entries>

id

Outputs a single entry matching the given entry ID.

<mt:Entries id="33">

include_subcategories

Boolean value, 1 or 0 (default). If specified in conjunction with the category (or categories) attribute, entries assigned to subcategories of the identified category/categories will be included.

lastn

Display the last N posts of the blog. N is a positive integer.

This attribute implies selection of entries based on their “authored” date (“Published Date” in the app), in reverse chronological order.

Movable Type will follow the value for “Entry Listing Default” preference in the Entry Settings if this attribute is not provided.

A value of “0” (zero) will output all entries.

Publish the 5 most recent entries, ordered by their title:

<mt:Entries lastn="5" sort_by="title" sort_order="ascend">

Note: when sorting use the limit attribute; when using lastn it is assumed that recent entries are desired.

limit

Used in Entry Listing archive templates or when sorting by a value other than by publish date. Can be a positive integer or “auto” (note that this value is case-sensitive), which defaults to the “Entry Listing Default” preference in the Entry Settings. Similar to the lastn attribute.

max_score

Returns entries with a score lower than the max_score value for the given namespace (required) for the scoring framework.

min_score

Returns entries with a score higher than the min_score value for the given namespace (required) for the scoring framework.

max_rate

Returns entries with a rate with the highest average score for the given namespace (required) for the scoring framework.

min_rate

Returns entries with the lowest average score for the given namespace (required) for the scoring framework.

max_count

Returns entries with which have been scored the most number of times (with any score) for the given namespace (required) for the scoring framework.

min_count

Returns entries with which have been scored the least number of times (with any score) for the given namespace (required) for the scoring framework.

namespace

Used to specify which scoring framework namespace to use when sorting by score (sort_by=”score”) or filtering based by score (max_score, min_score, max_rate, min_rate, max_count, min_count).

The MT Community Pack provides a community_pack_recommend namespace, for instance, which can be used to select entries, sorting by number of “recommend” or “favorite” scores that have been submitted.

offset

Used in coordination with lastn, starts N entries from the start of the list.

If dynamic publishing has been enabled, N is a positive integer or the keyword “auto” (note that this value is case-sensitive) to automatically determine the offset based on the offset query parameter for the request.

This code will place the first three entries in heading 2 tags and then place the rest in an unordered list:

<mt:Entries lastn="3">
<h2><$mt:EntryTitle$></h2>
</mt:Entries>
<ul>
<mt:Entries offset="3">
    <li><$mt:EntryTitle$></li>
</mt:Entries>
<ul>

recently_commented_on

Display the N most recently commented-on entries. Each entry will appear in the list only once. N is a positive integer.

<mt:Entries recently_commented_on="10">

Entries are in descending order by comment date.

sort_by

Defines the data to sort entries. The default value is “authored_on”. Accepted values are:

  • authored_on - (default) date/time when the entry was published. Editable through the MT user interface.
  • author_id
  • basename
  • comment_count
  • created_on - date/time when the entry was created. Not editable via MT user interface.
  • excerpt
  • keywords
  • modified_on - date/time when the entry was last modified. Not editable via MT user interface.
  • ping_count or trackback_count
  • rate (requires use of namespace attribute)
  • score (requires use of namespace attribute)
  • text
  • text_more
  • title

  • field:BASENAME where BASENAME is the basename of a custom field

    Warning: There is a bug 98025 with this attribute as of MT4.261 that causes the mt:Entries loop to lose blog context when using the field:basename in archive entry listing templates. This issue does not exist in index templates.

    Workarounds have been found by using another attribute to set context:

    Using the include_blogs attribute:

    <$mt:blogid setvar="blog_id"$>
<MTEntries sort_by="field:your_custom_field" include_blogs="$blog_id">
  ...
</MTEntries>

    or in a Category Entry Listing archive using the category attribute:

    <$mt:ArchiveTitle setvar="category_label"$>
<MTEntries category="$category_label" sort_by="field:your_custom_field">
  ...
</MTEntries>

Use the limit attribute when sorting as lastn assumes that recent entries are desired.

scored_by

Allows filtering of entries that were scored by a particular user, specified by username. Requires the namespace attribute.

sort_order

Accepted values are “ascend” and “descend”. Default order is the order specified for “Entry Order” in the Entry Settings. Use the limit attribute when sorting as lastn assumes that recent entries are desired.

<mt:Entries sort_order="descend">

tag

Filters entries by specified tag; published and private tags are supported values. The Boolean operators (AND, OR, NOT, parenthetical grouping) described for category selection are also supported for the tag attribute.

Output all entries tagged with “cats”:

<mt:Entries tag="cats">

Output the opposite (all entries that are not tagged “cats”):

<mt:Entries tag="NOT cats">

Output all entries tagged “cats” and tagged “dogs”:

<mt:Entries tag="cats AND dogs">

Output all entries tagged “cats” but not tagged “dogs”::

<mt:Entries tag="cats AND NOT dogs">

tags

Alias of tag attribute.

unique

Filters out entries that have been previously published on the same page using another <mt:entries> tag. Values 1 or 0 (default).

The second Entries tag will exclude any entries that are output from the first Entries tag:

<mt:Entries tag="@featured" lastn="3">
    <$mt:EntryTitle$>
</mt:Entries>
<mt:Entries lastn="7" unique="1">
    <$mt:EntryTitle$>
</mt:Entries>

Combination of Attributes and Modifiers

Attributes can be combined to display entries such as the most recent entry in the “Important” category:

<mt:Entries lastn="1" category="Important">

Repeated modifiers are all processed:

<mt:Entries regex_replace="regex1" regex_replace="regex2">

Order of attributes and modifiers is important.

Trim to ten characters and then limit to the last 10 words:

<mt:Entries trim_to="10" words="10">

Limit to the last 10 words and then trim to 10 characters:

<mt:Entries words="10" trim_to="10">

Examples

Most Recent Entries

This code is typically use in an index template:

<ul>
<mt:Entries lastn="10">
    <li><a href="<$mt:EntryPermalink$>"><$mt:EntryTitle$></a></li>
<mt:Entries>
</ul>

Recently Modified Entries

The 25 most recently modified entries (most recent on top) in an index template:

<ul>
<mt:Entries sort_by="modified_on" sort_order="descend" limit="25">
    <li><$mt:EntryModifiedDate format="%Y-%m-%d"$> - <a href="<$mt:EntryPermalink$>"><$mt:EntryTitle$></a></li>
</mt:Entries>
</ul>

Complex Example

In the default templates for MT4, there are some tricky conditional items used within <mt:Entries>. A simplified version of the default loop looks like this:

<MTEntries>
<$MTEntryTrackbackData$>
<div id="entry-<$MTEntryID$>">
    <h2 class="asset-name"><a href="<$MTEntryPermalink$>"><$MTEntryTitle$></a></h2>
    By <$MTEntryAuthorLink show_email="0"$> on <$MTEntryDate format="%x %X"$> |
    <a class="permalink" href="<$MTEntryPermalink$>">Permalink</a> | 
    <a href="<$MTEntryPermalink$>#comments">Comments (<$MTEntryCommentCount$>)</a> |
    <a href="<$MTEntryPermalink$>#trackback">TrackBacks (<$MTEntryTrackbackCount$>)</a>
    <$MTEntryBody$>
    <div class="entry-tags">
        <h4>Tags:</h4>
        <ul class="entry-tags-list">
            <li class="entry-tag">
            <MTEntryTags glue=",</li> <li>">
                <a href="<$MTTagSearchLink$>&IncludeBlogs=<$MTBlogID$>" rel="tag"><$MTTagName$></a>
            </MTEntryTags>
            </li>
        </ul>
    </div>
    Continue reading <a href="<$MTEntryPermalink$>#more"><$MTEntryTitle$></a>.
</div>
</MTEntries>

Display entries which are in the same category as the current entry:

<$MTEntryCategory setvar="entry_category"$>
<MTEntries category="$entry_category" glue=", ">
    <a href="<$mt:EntryPermalink$>"><$mt:EntryTitle$></a>
</MTEntries>

Display entries which have the same tags as the current entry:

<mt:EntryIfTagged>
    <$mt:EntryID setvar="entry_id"$>
    <mt:SetVarBlock name="entry_tags"><mt:EntryTags glue=" OR "><$mt:TagName$></mt:EntryTags></mt:SetVarBlock>
    <mt:SetVarBlock name="related_entries">
        <mt:Entries tags="$entry_tags">
            <mt:SetVarBlock name="related_entry_id"><$mt:EntryID$></mt:SetVarBlock>
            <mt:Unless name="related_entry_id" eq="$entry_id">
                <li><a href="<$mt:EntryPermalink$>"><$mt:EntryTitle$></a></li>
            </mt:Unless>
        </mt:Entries>
    </mt:SetVarBlock>
    <mt:If name="related_entries">
        <h2>Related Entries</h2>
        <ul>
            <$mt:Var name="related_entries"$>
        </ul>
    </mt:If>
</mt:EntryIfTagged>
Back

3 Comments

Marc Boucher on October 14, 2009, 10:55 a.m. Reply

Although the documentation says the days attribute will ignore the days attribute if used with another attribute my experience says otherwise, at least while using the offset attribute. I’m using offset and days together with no issues.

“The days attribute should be used separately from other attributes. If used with another attribute, days is ignored.”

thewired on September 21, 2010, 4:21 p.m. Reply

The attribute include_subcategories doesn’t always work properly. For example you have a parent category named Food. Under it you have a subcategory named Breakfast. Breakfast contains entries but Food does not. In this case the following tag will not work, and no entries will be listed:

<mt:Entries category="Food" include_subcategories="1">
    <$mt:EntryTitle$>
</mt:Entries>

Instead use:

<mt:EntriesWithSubCategories category="Food">
    <$mt:EntryTitle$>
</mt:EntriesWithSubCategories>
Maarten Schenk

Maarten Schenk on February 1, 2011, 1:55 a.m. Reply

The documentation of the ‘days’ attribute is incorrect. It says only positive integers are allowed, but numbers with decimal points also work. I have exploited this option to show only future entries by setting it to ‘0.0000000000001’: http://www.movabletips.com/2011/02/how-to-publish-only-future-entries-in-movable-type.html

(Setting it to zero directly won’t work, as the zero value is ignored.)