Applications

This Movable Type plugin implements a set of template tags for displaying text in multiple columns. Your text will be broken up into approximately equal portions, and the HTML formatting you specify (i.e. a table cell) will be repeated once for each portion.

Installation

To install the Columnize plugin, upload the file Columnize.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.

An Example

The individual MTColumnize tags are described below, but it's probably easiest to get a handle on how they all work together by taking a look at the following commented example. It displays each entry with the body text broken into 3 columns.

<!--standard MT code to loop through entries-->
<MTEntries>
 <span class="title"><$MTEntryTitle$></span>

 <!--begin the one-row table that'll contain the columns-->
 <table cellspacing="0" cellpadding="0" border="0">
  <tr valign="top">

   <!--begin our columnizing; all the other tags must be within MTColumnize-->
   <MTColumnize cols="3" min_chars="300">

    <!--the contents of MTColumnizeText will be broken into columns-->
    <MTColumnizeText>
     <$MTEntryBody$>
    </MTColumnizeText>

    <!--now we define the formatting that will be repeated for each column-->
    <MTColumnizeColumn>
     <td align="left">
      <span class="blogbody">
       <!--here's where the portion of text for each column will go-->
       <$MTColumnizePortion$>
      </span>
     </td>

     <!--the contents of MTColumnizeSpacer will be repeated for every column except the last one-->
     <MTColumnizeSpacer>
      <td>&nbsp;&nbsp;</td>
     </MTColumnizeSpacer>

    </MTColumnizeColumn>

   </MTColumnize>
  </tr>
 </table>
</MTEntries>

Although this plugin was designed to be used to generate a table-based column structure, you can see from the example that the tags don't "know" anything about table rows or cells. They simply break up some text into pieces, and insert each piece into a new instance of whatever formatting you define. Thus they could conceivably be used with CSS-based columns—for example, by defining three different styles called something like col1, col2, and col3, and using MTColumnizeColNum to assign the correct style to each column. If you try this, I'd be interested to hear whether it actually works.

Them's the Breaks

There are two basic ways to use this plugin. One approach, if you want to display an entire listing in columns (such as a listing of entry titles, categories, archive pages, or fairly short entries), is to put your entire looping tag (MTEntries, MTCategories, etc.) inside MTColumnizeText, and use the MTColumnizeBreakHere tag at the end of each item to indicate where the text can be broken. The documentation for MTColumnizeBreakHere has an example and further explanation of this method.

The other, more straightforward application of the plugin is simply to break up your entry body into columns, as in the example above. Obviously, this only makes sense if you have relatively lengthy entries.

This approach has some caveats with regard to where the text will be broken. If it doesn't see MTColumnizeBreakHere within your text, the plugin will break the text at spaces between words, trying to create columns that are approximately equal in length. However, the plugin doesn't know anything about line breaks or what the components of your text might be, so if you include more elements than just MTEntryBody in the text, you're liable to get column breaks at inopportune places. And if your entries contain types of content that should only be broken between lines, such as verse or programming code, columnizing your entry bodies probably isn't a great idea.

Then there's the issue of breaking in the middle of an HTML tag, or between a tag and its closing tag. The plugin does have some simple (well, simple-minded) code that tries to avoid breaking a single tag. But since it doesn't go so far as to actually parse the HTML in the text, it can't deal with nested tags. In other words, if your entries have a lot of HTML markup (beyond, say, a few links), you're likely to get some screwy results.

MTColumnize

This container tag is a wrapper for the other tags. In order for it to display anything, it must contain an MTColumnizeText tag and an MTColumnizeColumn tag (which should contain an MTColumnizePortion tag). The other tags are optional.

The tag takes the following attributes:

cols="N" (required)
The number of columns into which to divide the text.
min_chars="N" (optional)
If you have some very short entries mixed in with your longer ones, you might not want to break those into columns at all (15 words divided into 3 columns doesn't look so hot). The min_chars attribute is a threshold length: if the text within MTColumnizeText is shorter than N characters, it will not be broken up. The formatting defined in MTColumnizeColumn will still be applied, but only one column will be created.

MTColumnizeText

This container tag delimits the text that will be columnized. It doesn't display anything by itself, but it stores its contents for MTColumnizeColumn to work with. Therefore, it must come before MTColumnizeColumn within MTColumnize.

MTColumnizeColumn

This container tag contains the formatting code for a column. The tag loops over its contents for the desired number of columns. Within this tag, use MTColumnizePortion to indicate where each piece of the columnized text should appear.

MTColumnizeSpacer

This container tag must be used within MTColumnizeColumn. The contents of MTColumnizeSpacer will be displayed in every column except the last one. This allows you to add spacing or other formatting between your columns if desired.

MTColumnizePortion

Within MTColumnizeColumn, displays the current column's portion of the text.

MTColumnizeColNum

Within MTColumnizeColumn, displays the number of the column currently being displayed. This might be used in conjunction with appropriately named CSS styles to implement non-table-based columns.

MTColumnizeBreakHere

Within MTColumnizeText, inserts a placeholder that MTColumnizeColumn will use when deciding where to break the text. It's important to realize that this tag does not force a column break each time it appears, but simply indicates a potential place to break. (Think of it as "CanBreakHere.") If you use this tag, the plugin will only break at places where the tag appears, and nowhere else. Therefore, it really only makes sense to use it within a looping tag that creates a list, which in turn should be enclosed in MTColumnizeText.

The following example will display a 2-column listing of all your categories:

<table cellspacing="0" cellpadding="0" border="0">
 <!--here's another way to do spacing (without MTColumnizeSpacer),
 since we know there will be only 1 row below-->
 <tr>
  <td>&nbsp;</td>
  <td rowspan="2">&nbsp;&nbsp;</td>
  <td>&nbsp;</td>
 </tr>
 <tr valign="top">
  <MTColumnize cols="2">
   <MTColumnizeText>
    <!--we want the entire listing within MTColumnizeText-->
    <MTCategories show_empty="1">
     <a href="<$MTCategoryArchiveLink$>"><$MTCategoryLabel$></a><br>
     <$MTCategoryDescription$><br>
     <!--we only want to break after a category-->
     <$MTColumnizeBreakHere$>
    </MTCategories>
   </MTColumnizeText>
   <MTColumnizeColumn>
    <td>
     <span class="side">
      <$MTColumnizePortion$>
     </span>
    </td>
   </MTColumnizeColumn>
  </MTColumnize>
 </tr>
</table>

The placeholder string that MTColumnizeBreakHere inserts is ~BH~. If the text you're columnizing happens to contain this string for some odd reason, you can change the placeholder to something else (it should be something short, or it might throw off the calculation of column lengths) by modifying this line of code near the top of Columnize.pl:

$break_here_str = '~BH~';

Version History

9/21/04 - version 1.11

Column break will now come immediately after a tag instead of at the next following space, which was breaking tags in some cases (eclecticsoul).
Added code to allow direct use of "break here" string within entry text (Ferrie Maaswinkel).

7/12/04 - version 1.1

Plugin now registers itself with MT 3 interface.
Added package declaration and $VERSION variable.
All container tags now pass conditions along when building contents, so they'll work outside conditional tags within MTEntries, etc.

3/19/04 - updated documentation to reflect the fact that MTColumnizeSpacer must be used within MTColumnizeColumn (Benjamin Heitmann)

7/18/02 - version 1.0 released