Topicon v1.2.2 "Topic Icons" Plugin for Movable Type (c) 2002-2005 by John Addis http://www.a42.net/topicon NOTE === The included topicon.cfg file is a sample only! You will need to customize it for your installation. See the CONFIGURATION section for details. LICENSE ======= This is free software, distributed under a BSD-style license. Please see the file LICENSE for details. REQUIREMENTS ============ A recent version of Movable Type. Tested with version 2.5 See http://www.movabletype.org IMPORTANT ========= If you are upgrading from a version prior to 1.2.0 you MUST move your configuration data out of the topicon.file and into topicon.cfg. See the CONFIGURATION section below. BASIC INSTALLATION ================== 1) Place the 'topicon.pl' file in your Movable Type plugins directory. See the Movable Type user manual for more information on plugins. 2) Copy the 'topicon.cfg' file to your Movable Type plugins directory. You will need to customize that file for your server setup. 3) Create a "topicons" directory in your blog directory and put your icons in it. (See below for how to name icon files.) DESCRIPTION =========== Overview -------- Topicon allows you to associate "icons" (any image file) with a Movable Type category. It provides one new tag: which takes no parameters. This tag will be replaced by an HTML tag that points to the appropriate icon. How Icons are Named ------------------- Topicon takes the "label" of the category and performs the following transformation on it: 1) All single and double quotes are removed. 2) All characters other than A-Z, a-z, 0-9, . and - are converted to underscores. Multiple consecutive characters become a single underscore. 3) The entire text is converted to lower case. Ex: "This is a name" becomes "this_is_a_name" "John's Blog" becomes "johns_blog" Where Icons Are Found --------------------- By default, topicon looks for a subfolder called "icons" in your blog folder. You can change this by adding the variables "blog_icon_path" and "blog_icon_url" in topicon.cfg Image Types ----------- By default, Topicon looks first for a file with the ".png" extension, then for a ".gif", and finally for a ".jpg" file. You can add or remove file types and/or change the order by adding an "extensions" variable to topicon.cfg. The first matching file becomes the topic icon. System Icons ------------ You can also create a "system-wide" icon location by adding the variables "site_icon_path" and "site_icon_url" to topicon.cfg. This area will be searched (using the same algorithm as above) if a blog-specific icon isn't found. How to Use ---------- You'll need to modify your Movable Type templates to insert the tag. I like mine right after the entry title. The default "Main Index" template has the following:

which I change to:

If you apply more than one category you can show them all with the following:

&nbs; 

You'll probably also want to modify the "Individual Entry Archive" template. Once you've added the new tags you'll need to rebuild any affected pages. Customizing the HTML -------------------- You can add arbitray options to the generated image tag by specifying them as part of the MTTopicIcon tag, like this: Also, you can specify "%c" to insert the category label/name: Assuming the name of the category is "Stuff," this would generate a tag something like: -- Stuff -- To insert a literal % simply use %%: Again assuming "Stuff" as the name of the category, this would become something like: --Stuff:50% done-- As of version 1.2, it is possible to specify the text to display when an icon isn't found by using the new "deftext" attribute: CONFIGURATION ============= In versions of Topicon prior to 1.2.0 it was necessary to manually edit topicon.pl in order to change the configuration. As of 1.2.0 topicon uses a configuration file called topicon.cfg which should be placed in your plugins directory. The format of the file is as follows: variable-name = value Comments beginning with '#' and blank lines are ignored. The recognized variable-names are: extensions ---------- Lists the allowed filename extensions for image files, in preferred order. Default: extensions = png gif jpg blog_icon_path -------------- The path on the local (to the webserver) file system where image files are searched. This path is relative to the blog directory. Default: blog_icon_path = icons blog_icon_url ------------- The relative URL for the location where images are found. Default: If not specified, the value from blog_icon_path will be used. site_icon_path -------------- The absolute path to the local directory for system-wide icons. Ex: /usr/home/jaddis/www/topicons Default: If not specified, system-wide icons are not used. site_icon_url ------------- The absolute URL for site-wide icons. Ex: site_icon_url = http://www.a42.net/topicons Default: If not specified, system-wide icons are not used. DEBUGGING ========= Version 1.2.2 adds a new tag, MTTopicIconDebug. The syntax is exactly the same as MTTopicIcon but instead of producing an tag it will generate a table of information about your topicon setup. If you get stuck, try it. SUPPORT ======= If you have questions, problems, etc. you can check my website at http://www.a42.net/topicon or email me at john@a42.net CONTRIBUTORS ============ John Addis Timothy Carl Buchheim