David Raynes

I am sure all of you folks who have been using my plugin are dreading having to recreate your category hierarchy now that the code has moved into the MT core. Well, here is a script that I whipped together to migrate your data from the plugin version to the MT core version (as of version 3.1).

Download plugin-to-db.txt, rename it to plugin-to-db.cgi, upload it to your base MT directory, change its permissions so it can be excuted (usually 755), and then run it in your browser. When you are finished, be sure to remove the file from your MT installation.

I have only tested this on my installation as I was upgrading from 3.0D to 3.11, but it worked just fine for me.

Important Note: When upgrading to a 3.1x version of MT, remove all of the files associated with the SubCategories plugin before starting the upgrade.

Since the plugin contest deadline was extended, I thought I would spend some time making more improvements to SubCategories and this is what I came up with.

Download one of the following:

• subcats-1.2.tar.gz
• subcats-1.2.zip

New in this version:

• Category Label Delimeter: When you create a category, you can string together a hierarchy of categorys by putting all the category names in one category and seperating them with the configured delimeter (defaults to '::').
• ( Experimental ) Parent Category Archive Rebuilding: If turned on, when an entry is saved with a primary category set, the category archive for each ancestor of that primary category will be rebuilt.

More information and examples can be found in the SubCategories documentation

Update: Just to make sure I am explicitly clear, these are both MT 3 only features.

Another Update: Okay, a bit of a hiccup on my part. I managed to leave a bug in the Category Label Delimeter code when I moved from the testing version to using the config values (unfortunately, callbacks in MT do not generate immediately obvious errors; you have to go look in the activity log). It has been fixed and the version on the site has been updated. So, if you downloaded it before about 1100 (EDT) on Monday, get it again.

Okay, the automatic category hierarchy creation feature I mentioned in the previous entry is working and checked into my repository. Next in line is an experimental feature (akin to parts of MultiBlog) that will rebuild category archives for parent categories when an entry is posted to the child category. Testing it is part of the reason that I am writing this right now. :)

Update: It works, for me at least.

I successfully tested a big new feature for SubCategories last night: automatic creation of category hierarchies. This is a MT 3 specific feature. To make use of this feature, you would simply need to create a category containing multiple category names seperated by a specified delimeter (I'll use '::' in this example).

So, if you create this category through the regular MT interface:

Alpha :: Beta :: Gamma

The following category hierarchy will be created:

• Alpha
  • Beta
    • Gamma

Alpha and Beta will only be created if they do not exist already. If both Alpha and Beta do currently exist in the blog, creating a category named Beta :: Gamma would also produce the same result, assuming the relationship between Alpha and Beta have already been created.

One question just occurred to me. Does anybody want to be able to create multiple categories at the same level. For example:

Alpha :: Beta :: Gamma, Delta

• Alpha
  • Beta
    • Gamma
    • Delta

Is anybody out there using the latest SubCategories release on MT 2.x? I just finished helping somebody work on their site and I ended up having to downgrade them to 0.4 (a custom version, though, that I wrote a week or so ago). Unfortunately, debugging CGI is difficult remotely, and plugins are even harder. Please let me know if you are having any problems using SubCategories 1.0 and MT 2.x together.

Okay, so I have been convinced by denizens of #joiito (and I'm sure Zempt users would not mind either) to at least make an attempt to work SubCategories into MT's XML-RPC interface. Unfortunately, I am a little unfamiliar with that technology, as well as MT's implementation of it.

So, while I am learning, does anybody out there have any preferences on how I should work it up? Patch to MT code? New XML-RPC methods? Any suggestions on how the category hierarchy should be returned to the client?

SubCategories 1.0 is here! And there was much rejoicing. (Yay!)

You can download it here:

• subcats-1.0.tar.gz
• subcats-1.0.zip

Some of the more significant changes from the previous release (0.4):

• Much much improved interface (specially designed to make use of MT 3.0's CSS)
• Significant clean-up of the code
• Addition of the rayners::SubCategory API for other plugin developers
• Improved interface
• New tags: MTTopLeveParent, MTIfIsAncestor, MTIfIsDescendant
• Fixed a number of nagging bugs
• MTSubCategories (and MTTopLevelCategories): setting sort_order to 'descend' actually works correctly now
• MTSubCategories (and MTTopLevelCategories): new attribute sort_method allows you to define a custom category sorting method
• MTSubCatsRecurse: new attribute max_depth gives you control over how deep into the category hierarchy you want to go in your template
• Did I mention the improved interface?
• Should still be compatible with MT 2.x (not extensively tested though)
• MT 3.0 feature: when a category is removed via the MT interface, it is also removed from the hierarchy (i.e. the parent of its children will be set to its parent). If you are still using MT 2.x, those children will be listed as orphaned categories in the interface.

Be sure to read the SubCategories documentation for installation instructions and complete template tag and API documentation.

I spent a very large amount of time fixing bugs, implementing features, and just adding polish to this new version of SubCategories. If it proves useful to you, you might want to consider donating or purchasing something on my Amazon wish list (links coming shortly). I very much enjoy working on all my plugins, and I make them available for free, but they do take up a great deal of my time.

Enjoy!

It is 2am and I have been coding, tweeking, and debuging SubCategories for the last few hours. Unless I have any more feature ideas over the next day, or find any bugs, SubCategories Version 1.0 will be released tomorrow evening (East Coast Time).

I hope everybody appreciates the enormous amount of work I have put into making this release as robust and useful as possible.

I have made the decision to maintain documentation for all of my plugins in a wiki. Part of me wants to try to do it in the blog, but that is becoming impractical (plus a wiki makes it easier to recruit others to help out). I will still continue to make development news and release announcements here, but the documentation will be kept in the wiki I have setup. So far, all that has been created is the documentation for SubCategories, but more will be coming in the next few weeks as I find the time.

Barring any bugs, this release candidate will become the official 1.0 release of the SubCategories plugin.

Changes from the last release candidate:

• POD documentation for rayners::SubCategory
• Added IfIsAncestor and IfIsDescedant tags
  • IfIsAncestor takes one argument, child, and will return true if the category child is below the current category in the hierarchy.
  • IfIsDescendant takes one argument, parent, and will return true if the category parent is above the current category in the hierarchy.

Download one of the following files:

• subcats-1.0rc4.tar.gz
• subcats-1.0rc4.zip

The files need to be installed as follows:

• sub_cats.pl: in the plugins/ directory
• mt-sc.cgi: in the base MT directory, and be sure its permissions are set correctly (chmod 755)
• SubCats.pm and SubCategory.pm: in extlib/rayners/

Changes from 1.0 Release Candidate 2:

• Fixes a couple major bugs
• Added a new container tag: TopLevelParent which resolves to the highest parent category for the current category

Download one of the following files:

• subcats-1.0rc3.tar.gz
• subcats-1.0rc3.zip

The files need to be installed as follows:

• sub_cats.pl: in the plugins/ directory
• mt-sc.cgi: in the base MT directory, and be sure its permissions are set correctly (chmod 755)
• SubCats.pm and SubCategory.pm: in extlib/rayners/

(Okay, so release candidate 1 was pretty short lived)

Here is a release candidate for SubCategories, with added support for the new functionality available in Movable Type 3.0 (though it should be compatible with MT 2.x, but I have not tested it), along with a significantly improved user interface and an API for other plugin developers.

Download one of the following files:

• subcats-1.0rc2.tar.gz
• subcats-1.0rc2.zip

The files need to be installed as follows:

• sub_cats.pl: in the plugins/ directory
• mt-sc.cgi: in the base MT directory, and be sure its permissions are set correctly (chmod 755)
• SubCats.pm and SubCategory.pm: in extlib/rayners/

There are a couple more minor feature additions I need to make, and the SubCategory API needs to be documented. Other than that, however, it is pretty much it its final state. Hopefully there will not be too many bugs to fix. :)

Just to make sure everybody is aware of it, I am taking steps to make sure that the next release of SubCategories will be compatible with both MT 2.x and 3.0.

And here is a preview of the new and improved interface.

Here is what I have come up with so far. Please let me know if there is anything more I can provide.

rayners::SubCategory will extend the MT::Category class and provide the following additional methods:

• has_parent: Returns the id value of the parent (0 if the category has no parent)
• has_children: Returns true if the list of children for the category is defined
• children_categories: Returns the list of immediate children categories (i.e. only the children on the next level down) as rayners::SubCategory objects
• is_ancestor: Returns true if the category is an ancestor of the given category (e.g. true if $parent->is_ancestor ($child))
• is_descendant: Returns true if the category is a descendant of the given category (e.g. true if $child->is_descendant ($parent))

Here is some Perl code that can be used to integrate this with a plugin:

my $category_class = "MT::Category";
my $subcategories_available = 0;
eval {
    require rayners::SubCategory;
    $category_class = "rayners::SubCategory";
    $subcategories_available = 1;
};

my $cat = $category_class->load ($some_category_id);

Any thoughts, questions, or concerns?

I have decided to try and provide an interface to the SubCategories data for other plugin programmers (mostly because I want to use it in MultiBlog). Other than a method that will return the category hierarchy itself, are there any other methods anybody would like to have available?

I have sent out the second beta version to the testers. Significant improvements have been made to the plugin.

• Major UI improvements, including some JavaScript and the ability to unset the parent category of a child category (which was much requested).
• (New for MT 3.0) When a category is removed from MT, it is first removed from the category hierarchy.

Assuming testing goes well, a public version should hit the streets in a week or two.

Well, after staying up later than I probably should have, I seem to have a working version of SubCategories in MT 3.0D. I'll spend some time cleaning it up tomorrow and letting the volunteer beta testers, if there are any left now, take a whack at it while I start integrating some of the new MT 3.0 plugin features.

• New Tags:
  • MTHasNoSubCategories: the opposite of MTHasSubCategories
  • MTHasNoParentCategory: the opposite of MTHasParentCategory
  • MTTopLevelCategories: a container tag that acts just like MTSubCategories, except that it will always start at the top category level, instead of the current category if there is one
• New Attributes:
  • MTSubCategories (and MTTopLevelCategories) : sort_order: set to 'descend' to sort the categories in reverse order

Download the new version here:

• sub_cats-0.4.tar.gz
• sub_cats-0.4.zip

Thanks to some updates from Bjoern Graf, the following has been changed:

• Bugfixes:
  • Fix in the builtCatHeir method
  • Fixed bug in MTParentCategory: problem picking up on category in a category archive
  • Fixed bug in MTEntriesWithSubCategories: misbehavior when used in category archive

• New tags:
  • MTHasSubCategories: conditional tag that returns true if the current category has categories beneath it
  • MTHasParentCategory: conditional tag that returns true if the current category has one or more categories above it

• sub_cats-0.3.tar.gz
• sub_cats-0.3.zip

Enjoy!

This is just a minor bug-fix release. SubCategories should now correctly recognize the category when it is used in a category archive template.

• sub_cats-0.2.1.tar.gz
• sub_cats-0.2.1.zip

Enjoy!

Here are some big updates to the SubCategories plugin:

• Caches category hierarchy to improve rebuild times (thanks Brad)
• Updated web interface based on changes from Wai Siow
• Added a number of checks to interface
  • Category cannot be its own parent
  • Categories must be in the same blog
  • Permissions to edit categories must be present
  • Attempt to prevent cyclical hierarchies
• Added/Changed the following tags:
  • MTParentCategories:
    • Added exclude_current argument, to exclude the current category from the list
  • MTParentCategory:
    • Container tag for only the immediate parent of the current category
  • MTSubCategories:
    • Added include_current argument, to include the current category in the list
  • MTSubCategoryPath:
    • Based on Brad's suggestion, this is a short-cut tag for the following template code:

<MTParentCategories glue="/"><MTCategoryLabel dirify="1"></MTParentCategories>

Download from here:

• sub_cats-0.2.tar.gz
• sub_cats-0.2.zip

Here it is. Download one of the following files, unpack it, and place sub_cats.pl in your plugins/ directory and mt-sc.cgi in your base MT directory. mt-sc.cgi will probably need to be chmod'ed to 755 so it can be executed.

• sub_cats.tar.gz
• sub_cats.zip

It provides the following tags:

• MTSubCategories: a MTCategories replacement that handles the sub-categories you define
  • MTSubCatIsFirst: True if this is the first category in the current context
  • MTSubCatIsLast: True if this is the last category in the current context
  • MTSubCatsRecurse: use the current MTSubCategories container on the next lower level of categories (i.e. the sub-categories of the current category)
• MTParentCategories: a container tag that starts with the top-most parent of the category and loops its way down
  • glue: the text to use to tie the list together
• MTEntriesWithSubCategories: replacement for MTEntries that handles sub-categories
  • category: if the defined, it will select entries either in that category or in any of its sub-categories
  • any other arguments act exactly like MTEntries

Here are some usage examples that I've been using on my site:

Category List

<MTSubCategories>
<MTSubCatIsFirst><ul></MTSubCatIsFirst>
<li>
<MTCategoryLabel>
<MTSubCatsRecurse>
</li>
<MTSubCatIsLast></ul></MTSubCatIsLast>
</MTSubCategories>

Category Archive File Name (e.g. category/sub-category/sub-category/index.php)

archives/<MTParentCategories glue="/"><MTCategoryLabel
dirify="1"></MTParentCategories>/index.php

Category Breadcrumbs for an Entry

<MTEntryCategories glue=", ">
<MTParentCategories glue = "-&gt; ">
<a href="<$MTCategoryArchiveLink$>"
   title="<$MTCategoryDescription$>"><$MTCategoryLabel$></a>
</MTParentCategories>
</MTEntryCategories>

I also replaced all the MTEntries containers in my Category Archive Template with MTEntriesWithSubCategores to include all the sub-categories for the given category. You can also use the category list example in your Category Archive Template to produce a list of sub-categories.

To define how your categories relate to each other, just load up mt-sc.cgi in your web browser. With the dinky little interface I threw together, you can define the category -> sub-category relationship for your categories. The code will make sure that you do not define a category to be a sub-category of itself, but there are currently no safeguards against creating a sub-category loop (e.g. A is a sub-category of B which is a sub-category of A). If one of those is created, MT may get stuck in an infinite loop during your rebuilds (and therefore fail when the usual CGI timeout is hit).

Hopefully some (maye even most?) of that made sense. If you do not understand any part of this, please let me know and I will try and explain things more thoroughly.

( Note: This requires MT 2.6 or higher, and uses MT::PluginData, so the Storable perl module must be installed by your host )

Update: (2003-09-24 06:54)

I have added in some extra functionality to mt-sc.cgi thanks to Jay. Now it will print out a quick category heirarchy while you are editing. I still need to implement some kind of loop checking though. Anyways, enjoy!

For those of you that actually visit my site (as opposed to reading my feed), you may have noticed something unusual appear over the last few days. Well, I'd like to take a moment to explain what's going on. I am finishing up development and testing of a plugin that will give MT sub-category-like functionality. Certainly, it's not perfect, but it seems to be doing the job pretty well so far.

So, if you've got any particular requests for what a SubCategories plugin should do, please let me know. Assuming I've got most of the major issues worked out already, I should have a releasable version out by tomorrow night.