Applications

This very simple Movable Type plugin implements a template tag for displaying the first N words of an entry or any other text. While Movable Type's MTEntryExcerpt tag will automatically generate an excerpt consisting of the first N words of the entry body. However, you must configure the value of N for an entire blog, so you can't have excerpts of one length on one template and another length on another. This plugin allows you to display excerpts of different lengths in different places, and also lets you excerpt text other than an entry body.

Installation

To install the FirstNWords plugin, upload the file FirstNWords.pl to the plugins directory within your Movable Type directory. If you do not already have a plugins directory, create one before uploading the file. For more information about Movable Type plugins, see the documentation.

Support

Please use the support forums for all support requests, bug reports, feature requests, questions, and comments regarding this plugin.

MTFirstNWords

This container tag should be placed around the text you want to excerpt. Use the n attribute to specify how many words to display. As with MT's auto-excerpts, HTML will be removed from the text before the excerpt is generated.

The following example will display a listing of your categories, with the first 5 words of each category's description. It will add an ellipsis (...) to any description that had more than 5 words and was truncated.

<MTCategories>
 <p><a href="<$MTCategoryArchiveLink$>">
  <$MTCategoryLabel$>
 </a>: 
 <MTFirstNWords n="5" append="...">
  <$MTCategoryDescription$>
 </MTFirstNWords>
</MTCategories>

The tag takes the following attributes:

n="N" (required)
The number of words to display.
append="text" (optional)
If the tag's contents are more than N words, and are therefore truncated, the tag will add text to the end of the truncated contents. If the tag's contents are N or fewer words, nothing will be added. This allows you to specify an optional ellipse or other string. You can include MT template code in this attribute, using square brackets instead of angle brackets (and no dollar signs) and single quotes instead of double quotes. (To include a literal square bracket or single quote, escape it with a backslash.)
append_decode_html="1" (optional)
If you pass this attribute, HTML entities within the append string will be converted to the characters they represent. This allows you to use >, <, and " to include HTML code within the string. Note that the HTML decoding takes place before any MT template code within the string is evaluated.

The following code (within MTEntries) will present the first 20 words of an entry, followed by a "Read More" link if the entry was truncated:
```
<MTFirstNWords n="20" append="... &lt;a href=&quot;[MTEntryPermalink]&quot;&gt;Read More&lt;a&gt;" append_decode_html="1">
 <$MTEntryBody$>
</MTFirstNWords>
```
keep_trailing="1|characters" (optional)
If the truncated text ends with one or more punctuation symbols, the plugin will remove them unless you pass the keep_trailing attribute. If you never want to remove trailing punctuation, pass keep_trailing="1". If you want to keep only certain trailing characters, pass the characters you want to keep. For example, keep_trailing="?!" will cause an exclamation point or question mark at the end of the string to be retained, but will remove other punctuation characters.

Version History

7/12/04 - version 1.3

Plugin now registers itself with MT 3 interface.
Added $VERSION variable.

4/05/04 - version 1.2

Enhanced append feature with evaluation of MT template code and append_decode_html option (Carioca)
Added package declaration

9/22/03 - version 1.15

Trailing punctuation is now removed unless the new keep_trailing attribute is passed (Jake Brown)
Tag now passes conditions along when building contents, so it'll work outside conditional tags within MTEntries, etc.

12/7/02 - version 1.1

Added append attribute (luke)

9/3/02 - version 1.0 released