MTCollate 1.1

May 12, 2003 - updated February 8, 2006 (Download)

The listing tags that are built in to MovableType (MTEntries, MTCategories, etc.) have limited number of sorting options. For example, while you may sort entries chronologically, it is not possible to sort them descending by date, while ascending by time. Nor is it possible to intermingle different types of listings, for example a list of comments and trackback pings.

The MTCollate plugin gives you great flexibility in sorting listings (for example, descending by date while ascending by time) and allows you to list heterogeneous data (for example, entries, comment and trackback pings together sorted by time). It even allows you to sort by non-continuous values (for example, categories could be sorted by other than name or id).

How MTCollate Works

MTCollate works by building a virtual collection of records using the MTCollateCollect, MTCollateRecord and MTCollateSetField container tags. For example, the following code would create a collection containing 20 records, each of which consists of the fields “type”, “date”, “time”, “title”, “text” and “url”. Note that the first 10 records are filled with information from most recent entries while the next 10 records are filled with information from most recent comments.

<MTCollateCollect>
    <MTEntries lastn="20">
        <MTCollateRecord>
            <MTCollateSetField name="type">Entry</MTCollateSetField>
            <MTCollateSetField name="date"><$MTEntryDate format="%Y-%m-%d"$></MTCollateSetField>
            <MTCollateSetField name="time"><$MTEntryDate format="%H:%M:%S"$></MTCollateSetField>
            <MTCollateSetField name="text"><$MTEntryExcerpt$></MTCollateSetField>
            <MTCollateSetField name="title"><$MTEntryTitle$></MTCollateSetField>
            <MTCollateSetField name="url"><$MTEntryPermalink$></MTCollateSetField>
        </MTCollateRecord>
    </MTEntries>
    <MTComments lastn="20">
        <MTCollateRecord>
            <MTCollateSetField name="type">Comment</MTCollateSetField>
            <MTCollateSetField name="date"><$MTCommentDate format="%Y-%m-%d"$></MTCollateSetField>
            <MTCollateSetField name="time"><$MTCommentDate format="%H:%M:%S"$></MTCollateSetField>
            <MTCollateSetField name="text"><$MTCommentBody$></MTCollateSetField>
            <MTCommentEntry>
                <MTCollateSetField name="title">Comment for <$MTEntryTitle$></MTCollateSetField>
                <MTCollateSetField name="url"><$MTEntryPermalink$></MTCollateSetField>
            </MTCommentEntry>
        </MTCollateRecord>
    </MTComments>
</MTCollateCollect>

Once a collection has been built, its contents can be displayed using the MTCollateList and MTCollateField tags. MTCollateIfHeader and MTCollateIfFooter tags can be used to separate records that are listed, similar to MTDateHeader and MTDateFooter. For example, the following code displays 10 records for the previous collection, sorted descending by date and ascending by time within each day:

<MTCollateList limit="10 date:- time:-" sort="date:- time:+">
    <MTCollateIfHeader name="date">
        <div class="date">
        <MTCollateField name="date">
        </div>
        <div class="time">
    </MTCollateIfHeader>
    <MTCollateField name="time">:
    <a href="<MTCollateField name="url">"><MTCollateField name="title"></a>
    <div><MTCollateField name="text"></div>
    <MTCollateIfFooter name="date">
        </div>
    </MTCollateIfFooter>
</MTCollateList>

MTCollateTags

• MTCollateCollect
  Container tag that defines a collection of records. It does not display any text.
  • name=”collection name”
    This optional parameter assigns a name to the collection. You can have multiple collections as long as their names are unique.
• MTCollateRecord
  Container tag that defines a record in the collection. Must be located inside the MTCollateCollect tags.
• MTCollateSetField
  Container tag that sets a field in the current collection record. Must be located inside MTCollateRecord tags.
  • name=”field_name”
    This required attribute specifies the name of the field. The name should only consist of numbers, letters and underscore characters.
• MTCollateList
  Container tag that displays the records in an existing collection.
  • name=”collection_name”
    Optional attribute that specified the name of the collection.
  • sort=”field_name_1:option1:option2 field_name_2:option3:option4”
    The optional sort attribute specif how the records in the collection are sorted. The sort consists of a space-separated list of field names with optional sorting attributes, separated by colons (‘:’). The following attributes are supported:
    • ”+” or “ascend”
      This field is sorted in ascending order; smaller to bigger. This is the default sort.
    • ”-” or “descend”
      This field is sorted in descending order; bigger to smaller.
    • ”#” or “numeric”
      This field is compared numerically, i.e. 1 < 5 < 12. The default is string comparison, i.e. “1” < “12” < “5”.
    • “i” or “insensitive”
      This field is compared case insensitive (i.e. “Abc” = “ABC”). The default is case sensitive (i.e. “Abc” != “ABC”).
    • “[Val1,Val2,Val3]”
      The field is considered an enumeration of values and is sorted according to the specified, comma-separated list of values. If the field does not march any of the specified values, it is sorted after the values in the enumeration.
      The following example would sort entries by category in a specific order:

      <MTCollateList sort="category:[Diary,Photo,Essay]">
      ...
      </MTCollateList>
      

    • “d” or “distinct”
      This field is marked as distinct and the row will be ignored if it is a duplicate of a previous row. If more than one field is marked distinct, then two rows are considered duplicate if each distinct field is the same in both rows.
  • limit=”20” or limit=”20 date:descend time:descend”
    The limit attribute specifies the maximum number of records listing. It should be a number, optionally followed by sorting information (formatted like the sort attribute).
    You only need to specify the sorting information in this attribute if the display sort does not already specify it correctly. For example, if you want to list the 20 most recent entries in ascending order, you would have to specify it like so:

    <MTCollateList limit="date:descend time:descend" sort="date:ascend time:ascend">
    ...
    </MTCollateList>
    

  • offset=”n”
    Used in conjunction with the limit attribute to skip over the first n records in the list.
  • locale=”cs_CZ”
    Specifies which locale (language/character set) to use when doing text comparison. Any locale installed on your system may be specified (“german”, “de”, “de_DE”, “de_DE.iso88591”, “ru_RU.iso88595”, etc.) For example, to compare text according to American English rules, you might specify locale=”en_US”. To use Icelandic rules, you might specify locale=”is_IS”. The default is to do straight ASCII comparison.
    Note: Your system must be properly configured and the appropriate locales installed in order to use this feature. Please see Preparing to Use Locales for more information.
• MTCollateField
  Displays the value of the specified field in the current record. If the field does not exist, an empty string is displayed.
  • name=”field_name”
    Specifies the name of the field to be displayed.
• MTCollateIfHeader
  Container tag that displays its contents if this is the first record in the list, or if the value of the specified field differs from the same field in the preceding record.
  • name=”field_name”
    Specifies the name of the field to be compared.
• MTCollateIfFooter
  Container tag that displays its contents if this is the last record in the list, or if the value of the specified field differs from the same field in the following record.
  • name=”field_name”
    Specifies the name of the field to be compared.
• MTCollatePrevious
  Container tag that displays its contents in the the context to the preceding record, if any.
• MTCollateNext
  Container tag that displays its contents in the the context to the following record, if any.

• Version 1.1 - January 21, 2004
  Added “locale” attribute to MTCollateList.
• Version 1.01 - September 3, 2003
  Added “distinct” sort/limit attribute
• Version 1.0 - May 12, 2003