BlogsList (v1.1) Plugin User Documentation


NAME

The BlogsList plugin provides the Movable Type tags: MTBlogsList, MTBlogsIfInclude, and MTBlogTBPingCount.


SYNOPSIS

MTBlogsList is a Movable Type container tag offering a list of blogs for any user template, similar to the built-in MTBlogs tag. MTBlogsIfInclude is a conditional container tag controlling which blogs are available within its extent. This plugin also provides the MTBlogTBPingCount tag.

blogslist.pl identifies the plugin to MT and registers the methods provided. Related files provide user-based configuration services. For additional information see BlogsList.pm and mt-blogslist.cgi.

This help document provides examples of the tag uses and includes sample HTML and CSS that could enhance the results. An HTML version of this help information is provided for installation for the general user.

Enosis Group developed this plugin specifically for a client running (stuck at!) MT 3.16. All candidate alternatives were already at 3.2.


DESCRIPTION

There are two audiences:

Usage Information: Blog Owner or Editor

Sample use of the tags:

  <MTBlogsList sort_by="name" sort_order="ascend">
  <MTBlogsIfInclude id="1,2,5">
     Blog: <a href="<$MTBlogURL$>"><$MTBlogName$></a> 
        Entries <$MTBlogEntryCount$>
        Comments <$MTBlogCommentCount$> 
        TBPings <$MTBlogTBPingCount$>
  <MTElse>
     Excluded blog: <$MTBlogID$>
  </MTElse>
  </MTBlogsIfInclude>
  </MTBlogsList>

MTBlogsList has two optional attributes, sort_by and sort_order. MTBlogsIfInclude has two optional attributes, id and invert. MTBlogTBPingCount takes no attributes.

The MTBlogTBPingCount tag may be used in any single blog context, similar to the MTBlogCommentCount tag, including outside of MTBlogsList containers.

Without the optional tag attributes, the MTBlogsList tag gives results similar to the MTBlogs container tag.

That is:

   <MTBlogsList>
   </MTBlogsList>

is similar to:

   <MTBlogs>
   </MTBlogs>

The simplest enhancement that BlogsList offers: if you include sort_by="id", the results are sorted numerically on id (1,2,...,10), not lexically as in <Blogs> (1,10,2,....).

The attributes are explained further, below.

Notice for static pages: If you include the MTBlogsList tag on a static page, the listed blogs and the corresponding counts update only when that page is rebuilt. In a likely scenario, this tag would be used on an index page for a 'master' blog of a publication service. Although the other blogs of the publication service may be updated at any time, the display of blogs and counts on that 'master' page will only be updated when that static 'master' page is rebuilt. This is identical to the results and effect of MTBlogs and MTBlogCommentCount.

To provide your readers a more up-to-date service, consider: using dynamic pages for such pages; or specifically rebuilding any index page containing this tag whenever any of the blogs of the system are updated; or running a 'timed' update task using cron (for example) to update the index pages using the tag. Consider using display text to inform your readers, such as a timestamp in proximity to the blogs list.

Usage Information: Blog System Maintainer

The plugin is designed and tested as a standard MT plugin (Movable Type 3.16 is the only platform tested.)

It registers itself and is displayed on the blog editor's Main Menus (in the default templates, at the bottom), where links to configuration and documentation can also be found. If there isn't an entry for this plugin, you have an installation problem.

Installation Overview:

Install as a normal MT plugin, as follows:

 (mtplugins)/BlogsList/blogslist.pl
 (mtplugins)/BlogsList/BlogsList-v1_Doc.html (optional)
 (mtplugins)/BlogsList/blogslist.cfg (optional)
 (mtplugins)/BlogsList/BlogsList.css (optional)
 (mtplugins)/BlogsList/BlogsList_sample.html (optional)

For using the plugin configuration service (for the listing of blogs and any defined id lists), install the following:

 (mtplugins)/BlogsList/mt-blogslist.cgi (recommended)
 (mtplugins)/BlogsList/lib/BlogsList.pm (recommended)
 (mtplugins)/BlogsList/tmpl/list_blogslistcfg.tmpl (recommended)

No further adjustments are required; the following are optional.

BlogsList-v1_Doc.html (optional)

Copy the BlogsList-v1_Doc.html file to a location within the web server's publishing hierarchy. A typical location is the root directory shared by all the blogs of the installation. Confirm that the directory and file permissions are no more restrictive than those desired for blog editor access.

If you update blogslist.cfg with this location, in the HelpFileURL parameter, it will be linked off of the plugin configuration page.

blogslist.cfg (optional)

The configuration file has parameters to help users.

HelpFileURL, helps users find help information on the tags (from the link in the plugin at the bottom of their blog editor's page). Only one statement of this parameter is expected; the first is used.

The remaining items are named id lists defined for the installation, offering uniform lists of blogs ids to exclude. We recommend at least one conventional definition, for "global_exclude".

The configuration file will be found in either of two locations. If present at (CGIPath)/blogslist.cfg, this file takes precedence (even if empty, providing an override). (mtplugins)/BlogsList/blogslist.cfg will also be sought, and will be effective if the former file is missing. A brief report of the configuration file used is available from the configuration page ((mtplugins)/BlogsList/mt-blogslist.cgi).

blogslist.cfg example:

   HelpFileURL   http://domain.tld/our_blogs/BlogsList-v1_Doc.html

   #for id="" in blog page templates updated 1Jan95
   global_exclude 1,3,5,11,4      #maint and retired
   id_maint_blogs 1,5               #expect only nonsense
   news_blogs     6,7

The file consists of comment lines (beginning with #), and blank lines, both ignored. On any line a # preceded by at least a single space signals the beginning of a comment, upon which the remaining of the line is ignored. Parameters begin with a letter, and consist of alphanumerics and underscore. A space separates the parameter from the value, which extends from the first non-space character to the last non-space character. Quotes around the values will be ignored. The value of the named id list must be a series of integers, in any order, separated in some fashion with spaces and commas.

BlogsList.css (optional)

To provide a display compatible with the stock MT Calendar, integrate the BlogsList.css file into your system css. You may do this in several ways. The simplest may be updating your main css file with these styles. Alternatively, locate this file in the same directory as your main css, and update your main css with an @import "BlogsList.css" for this file. Note that the styles depend on the html id and classes as shown in BlogsList_sample.html.

Note:

The plugin does not track adds or deletions of blogs or entries or comments or pings.

Dynamic pages will update the counts on display to an MT request.

For static pages, however, the question of automatically rebuilding any static pages using the tag was thought likely to be too load intensive. The recommended solution is to run a cron service to update those pages using this tag, and when adding or deleting blogs to perform manual updates to the id lists on blog templates (or use blogslist.cfg named ids and <MTElse>).

Tag Attributes: MTBlogsList

These tag attributes are available for MTBlogsList:

sort_by="index_name"

A tag attribute used to specify the single index by which to sort the blogs. The value of this tag must be one of the indexes specified for the blog object, or the default key. This tag is built to support the only such index provided for blogs in unmodified MT 3.16: (name), in addition to the database key (id):

id is the default if sort_by is omitted when sort_order is, however, specified.

For example:

<MTBlogsList sort_by="name" >

Note: Without this tag, the blogs are sorted according to your MT install's 'native' order. This may vary according the type of file store used, and other considerations. The native order for file-based stores is lexical on the blog id, which results in an order something like: 1, 10, 11, 2, 3, ...

sort_order="ascend | descend"

A tag attribute used to specify the order for the default or specified sort_by field. If omitted and sort_by is specified the default is ascend.

For example:

<MTBlogsList sort_order="ascend">

This tag attribute must appear only once.

Tag Attributes: MTBlogsIfInclude

If you wish to alter MTBlogsList's automatic global inclusion of all of the system's blogs, use the MTBlogsIfInclude conditional tag.

Without a valid id attribute, the MTBlogsIfInclude will have no effect. In the presence of a valid id attribute, the invert="1" attribute inverts the effect of the conditional tag.

Note that this is an MT-standard conditional tag, so the MT-standard MTElse tag is relevant. If specified within the scope of MTBlogsIfInclude, MTElse demarks the content that will be displayed for any blogs which would otherwise be omitted through MTBlogsIfInclude's effect.

Although it makes only limited sense, MTBlogsIfInclude can be nested, in which case the resulting subset of blogs can be further restricted with an inner MTBlogsIfInclude using id and invert, to, e.g., remove truly administrative-only or ancient blogs.

These tag attributes are available for MTBlogsIfInclude:

id="numeric_list"

A comma-separated list of blog id numbers. Whitespace is okay.

id specifies the scope of effect for MTBlogsIfInclude. Without the attribute MTBlogsIfInclude has no effect (i.e., the contained content is displayed for all blogs).

If id is present, only blogs with an id found in the id value come under influence of the tag: without the invert="1" attribute (which is equivalent to invert="0"), no blogs are provided, except those listed in id; with the invert="1" attribute, all blogs are provided, except those listed in id.

For example:

   <MTBlogsList>
      <MTBlogsIfInclude id="1,3,5,9,2">
         your spec for list of 1, 2, 3, 5 & 9
      </MTBlogsIfInclude>
   </MTBlogsList>

This tag attribute must appear only once.

Also see the advanced use note below.

invert=" 1 | 0 "

When set to "1", the invert attribute inverts the effect of the conditional tag. It now becomes more like an (MT-antithetical) MTBlogsExclude id="" tag. Now, blogs with an id found in the id value will be excluded (and the content to display for such excluded blogs could be specified in a contained MTElse). The effect when set to "0" is equivalent to omiting the invert attribute altogether.

This tag attribute must appear only once.

In a blog CMS having blogs 1 through 5, both examples print blogs 3 and 4:

   <MTBlogsList>
      <MTBlogsIfInclude id="1,2,5" invert="1">
         Blog: <$MTBlogID$>
      </MTBlogsIfInclude>
   </MTBlogsList>

produces identical results to:

   <MTBlogsList>
      <MTBlogsIfInclude id="1,2,5">
      <MTElse>
         Blog: <$MTBlogID$>.
      </MTElse>
      </MTBlogsIfInclude>
   </MTBlogsList>
id="named_id_list"

Advanced: There is one further configuration for the value of the id parameter.

Operation of this advanced configuration requires: that the blogslist.cfg file is found in one of the above-mentioned directories; and, further, that the configuration file contains id list parameters of the format described here.

If these conditions are not met, the effect is the same as if id had not been specified (which is that all blogs are included in the resulting set). If these conditions are met, the value of the named id list, here news_blogs, becomes the value of the id= parameter.

For example, this list could be in your blogslist.cfg file:

    global_exclude    1,3,4,11,8
    id_maint_blogs    1,5
    news_blogs         6,7

And is used as:

   <MTBlogsList>
      <MTBlogsIfInclude id="news_blogs">
         Blog: <$MTBlogID$>
      </MTBlogsIfInclude>
   </MTBlogsList>

global_exclude is suggested as a convention you might follow to designate blogs that in your blog installation would ordinarily not be useful to list; it is not a special name.

Overall Use of The MTBlogsIfInclude Tag:

The overall logic behind this conditional tag is related to the logic for the MTBlogsList container tag: all blogs are listed by default.

Using id with invert provides a flexible facility where all newly created blogs would automatically be listed. But certain blogs are used for content management or testing, and should not usually be displayed -- once created their numbers are added to such a list (or, e.g., a global_exclude named id list). Users specifying these tags may note the ids of unwanted blogs, and add them to their own list for exclusion.

The goofy name has to do with honoring the MT naming convention of the 'context + If + InclusionCondition'. If course we're stuck with wanting the opposite effect, and didn't want something like 'MTBlogsIfIncludeUnless' or 'MTBlogsIfNotExcluded'.


SAMPLE MT BLOG TEMPLATE FRAGMENT

This is an example that could be inserted into your index template. With suitably-short blog names, the abbreviated column heads allow it to fit in the standard calender column.

  <div id="blogslist">
  <table summary="Snapshot of blogs and activity">
     <caption>Snapshot</caption>
     <tr><th class="timestamphead"><$MTDate 
                      format="%e%b%y %l:%M%p"$></th>
         <th>En</th><th>Co</th><th>Tb</th></tr>
     <MTBlogsList sort_by="name" sort_order="ascend">
       <MTBlogsIfInclude id="1,12,13,14" invert="1">
         <tr><td class="blogname"><a 
             href="<$MTBlogURL$>"><$MTBlogName$></a></td>
             <td><$MTBlogEntryCount$></td>
             <td><$MTBlogCommentCount$></td>
             <td><$MTBlogTBPingCount$></td></tr>
       </MTBlogsIfInclude>
     </MTBlogsList>
  </table>
  </div>

SAMPLE STYLESHEET FRAGMENT

This example is modeled on the calendar format, to have a comparable appearance.

   #blogslist {
        line-height: 140%;
        color: #666666;
        font-family: Verdana, Arial, sans-serif;
        font-size: x-small;
        padding: 2px;
        text-align: center;
        margin-bottom: 20px;
        }
   #blogslist table {
        padding: 2px;
        border-collapse: collapse;
        border: 0px;
        width: 100%;
        }
   #blogslist caption {
        color: #666666;
        font-family: Verdana, Arial, sans-serif;
        font-size: x-small;
        text-align: center;
        font-weight: bold;
        text-transform: uppercase;
        letter-spacing: .3em;
        }
   #blogslist th {
        text-align: center;
        font-weight: normal;
        }
   #blogslist td {
        text-align: center;
        }

AUTHOR & COPYRIGHTS

Author: Nick Ragouzis

Copyright (c) 2006 Enosis Group LLC. All rights reserved

This is free software.