root/tagwire/trunk/README.txt

Tagwire Plugin
$Id$

A plugin for handling entries' keywords as "tag" in Movable Type.

===========
DESCRIPTION
===========

Tagwire Plugin(aka AllKeywords Plugin) provides an easier way to
handling "tags" in Movable Type. The keywords fields of any entries
are used as "tags".

Unlike Tags and Tagslite Plugin, this plugin has the following
features:

- Multilingual Tagging:

- Flexible Tag Format:

- MT's categories are Untaint: Tagwire Plugin uses only "keywords"
  field of entries, so users can use "categories" just as themselves
  separately.

- Full-fledged support for tag handling: Tagwire provides various
  functions including blog-wide/entry-wise tag listing and counting,
  listing entries that have user-specified tags, and listing related
  entries.

- Moderate Rebuilding Time: Tagwire realizes tag indexing without
  support of your DB engines.  It often leads to performance
  degradation especially for rebuilding, but Tagwire employs
  PluginData and Request Cache effectively and achieves enough speed.

- Dynamic Tag Archiving coupled with MT-XSearch: Though Tagwire
  generates no static tag archives, it couples with Tim Appnel's
  MT-XSearch and supports Dynamic Tag Archiving.


============
INSTALLATION
============

To install this plugin, upload or copy 'tagwire.pl' into your Movable
Type's plugin directory.

After proper installation, you will see a new "Tagwire Plugin" listed
on the Main Menu of your Movable Type.


==========
TAG FORMAT
==========

Tagwire automatically interprets the string which inputs the keywords
field of the entry, as "tags". Any strings enclosed by brackets([,]),
sigle and double quotes are parsed as a single tag.  And any strings
separated by delimiter characters(;,|) are parsed as a single tag.
And if no delimiter characters appear, whitespaces work as delimter.

The following all examples are recognized as two tags "Movable Type"
and "Plugin":

        "Movable Type" Plugin
        Movable Type, Plugin
        Movable Type|Plugin|
        [Movable Type][Plugin]

And the following example is parsed as two tags "MT" and "Plugin":

        MT Plugin


====
TAGS
====

From here I will explain MT container/varable tags introduced by
Tagwire Plugin.

----------------
MTTags Container
----------------

A container tag for listing all available "tags" for the current blog.

* Option(s):

glue="glue"

    Separates each of the tags with a string specified by "glue".
    This is useful when you wish to separate the tag names with a
    comma, for example.

sort_by="tag|tag-case|count"

    Chooses sorting method for tags. "tag" means case-insensitive
    alphabetical sort, "tag-case" means case-sensitive alphabetical
    sort, "count" means sort by tag's count. Default setting is "tag".

sort_order="ascend|descend"

    Chooses sorting order. The default sort_order is "ascend".

lastn="N"

    Shows only last N tags. By default, all tags are displayed.

case_sensitive="0|1"

    Chooses whether the plugin treats tags as the case-sensitive
    manner or not.  In the case-sensitive manner, the plugin
    recognizes "Apple" and "appLE" as two different tags, on the other
    hand, it recognizes them as a same tag in the case-insensitive
    manner. The default is case_sensitive="1".

* Available tags in this container:

<$MTTag$>
    Shows the tag.

<$MTTagCount$>
    Shows the appearance count of the tag.

<$MTTagDate$>
    Shows the last date the tag added.

<$MTTagsTotal$>
    Shows the number of all tags.

<$MTTagsTotalSum$>
    Shows the total appearance count of all tags.

* Example:

To list 10 most appeared tags and link them to Technorati:

<ul>
  <MTTags sort_by="count" sort_order="descend" lastn="10">
  <li><a href="http://www.technorati.com/tag/<$MTTag encode_url="1"$>"
    rel="TAG" title="TAG:<$MTTag$>"><$MTTag$></a> (<$MTTagCount$>)</li>
  </MTTags>
</ul>
<ul>
  <li>Total Tags: <$MTTagsTotal$></li>
  <li>Total Tags(Sum): <$MTTagsTotalSum$></li>
</ul>

And Ogawa::Memoranda Tags(http://as-is.net/blog/tags.html) is an
example of using MTTags container.

---------------------
MTEntryTags Container
---------------------

A container tag for listing tags for an entry.  It can only be used in
"entry context" which means "the inside of MTEntries" or Individual
Archives.

* Option(s):

glue="glue"

    Separates each of the tags with a string specified by "glue".
    This is useful when you wish to separate the tag names with a
    comma, for example.

case_sensitive="0|1"

    Chooses whether the plugin treats tags as the case-sensitive
    manner or not.  The default is case_sensitive="1".

* Available tags in this container:

<$MTTag$>
    Shows the tag.

* Example:

To list tags of the entries and link them to Technorati:

<MTEntries lastn="10">
<h2><$MTEntryTitle$></h2>
 
<ul>
  <MTEntryTags>
  <li><a href="http://www.technorati.com/tag/<$MTTag encode_url="1"$>"
    rel="TAG" title="TAG:<$MTTag$>"><$MTTag$></a></li>
  </MTEntryTags>
</ul>
 
<$MTEntryBody$>
</MTEntries>

-----------------------
MTRelatedTags Container
-----------------------

A container tag for listing tags *related* to the current tag.  The
relationship between tags is defined by how many common *entries*
includes them.  This container can only be used in "tag context" which
means the inside of MTTags, MTEntryTags, or MTXSearchTags.

* Option(s):

glue="glue"

    Separates each of the tags with a string specified by "glue".
    This is useful when you wish to separate the tag names with a
    comma, for example.

sort_by="tag|tag-case|count"

    Chooses sorting method for tags. "tag" means case-insensitive
    alphabetical sort, "tag-case" means case-sensitive alphabetical
    sort, "count" means sort by tag's count. Default setting is "tag".

sort_order="ascend|descend"

    Chooses sorting order. The default sort_order is "ascend".

lastn="N"

    Shows only last N tags. By default, all tags are displayed.

case_sensitive="0|1"

    Chooses whether the plugin treats tags as the case-sensitive
    manner or not.  The default is case_sensitive="1".

* Available tags in this container:

<$MTTag$>
    Shows the tag.

<$MTTagCount$>
    Shows the appearance count of the tag.

<$MTTagDate$>
    Shows the last date the tag added.

* Example:

To list tags of the entries and their related tags, and to link all of them to Technorati:

<MTEntries lastn="10">
<h2><$MTEntryTitle$></h2>
 
<ul>
  <MTEntryTags>
  <li><a href="http://www.technorati.com/tag/<$MTTag encode_url="1"$>"
    rel="TAG" title="TAG:<$MTTag$>"><$MTTag$></a>
    <ul>
      <MTRelatedTags>
      <li><a href="http://www.technorati.com/tag/<$MTTag encode_url="1"$>"
        rel="TAG" title="TAG:<$MTTag$>"><$MTTag$></a></li>
      </MTRelatedTags>
    </ul>
  </li>
  </MTEntryTags>
</ul>
 
<$MTEntryBody$>
</MTEntries>

---------------------------
MTEntriesWithTags Container
---------------------------

A container tag for listing entries which have user-specified tags.

* Option(s):

tags="tag-list"

    User-specified tags for listing.  It can be a single tag or
    multiple tags separated by a delimiter.

delimiter="delim"

    Sets the delimiter character for the abovementioned "tags" option.
    The default delimiter is whitespaces.

case_sensitive="0|1"

    Chooses whether the plugin treats tags as the case-sensitive
    manner or not.  The default is case_sensitive="1".

sort_order="ascend|descend"

    Chooses sorting order. The default sort_order is "descend".

lastn="N"

    Shows only last N entries. By default, all entries including
    user-specified tags are displayed.

* Available tags in this container:

As like MTEntries container, various tags including MTEntry* are
available inside this container.

* Example:

To list all entries which have "movable" and "type" tag:

<MTEntriesWithTags tags="movable type">
<h2><a href="<$MTEntryPermalink$>"><$MTEntryTitle$></a></h2>
 
<$MTEntryBody$>
<$MTEntryExtended$>
</MTEntriesWithTags>

------------------------------
MTMostRelatedEntries Container
------------------------------

A container tag for listing entries *related* to the current entry.
The relationship between entries is defined by how many common *tags*
they have.  This container can only be used in "entry context" which
means "the inside of MTEntries" or Individual Archives.

* Option(s):

case_sensitive="0|1"

    Chooses whether the plugin treats tags as the case-sensitive
    manner or not.  The default is case_sensitive="1".

sort_order="ascend|descend"

    Chooses sorting order. The default sort_order is "descend".

lastn="N"

    Shows only N most related entries. By default, all related entries
    are displayed.

* Available tags in this container:

As like MTEntries container, various tags including MTEntry* are
available inside this container.

* Example:

To list 10 most related entries for the current entry:

<MTEntries>
<h2><a href="<$MTEntryPermalink$>"><$MTEntryTitle$></a></h2>
<$MTEntryBody$>
 
<ul>
<MTMostRelatedEntries lastn="10">
<li><a href="<$MTEntryPermalink$>"><$MTEntryTitle$></a></li>
</MTMostRelatedEntries>
</ul>
</MTEntries>

-----------------------
MTXSearchTags Container
-----------------------

A container tag for listing the query string of MT-XSearch as tags.
It can only be used in "MT-XSearch" Template.

* Option(s):

glue="glue"

    Separates each of the tags with a string specified by "glue".
    This is useful when you wish to separate the tag names with a
    comma, for example.

* Available tags in this container:

<$MTTag$>
    Shows the tag.

* Example:

To list tags given by the query string of MT-XSearch and their related tags, and to link them to Technorati:

<MTXSearchTags>
<h2><$MTTag$></h2>
 
<ul>
  <MTRelatedTags>
  <li><a href="http://www.technorati.com/tag/<$MTTag encode_url="1"$>"
    rel="TAG" title="TAG:<$MTTag$>"><$MTTag$></a></li>
  </MTRelatedTags>
</ul>
</MTXSearchTags>

---------------------
encode_urlplus Filter
---------------------

A variation of encode_url filter. First this filter converts
whitespaces of the target string into '+'s, and then converts it into
URL-safe string.

* Example:

<ul>
  <MTEntryTags>
  <li><a href="http://www.technorati.com/tag/<$MTTag encode_urlplus="1"$>"
    rel="TAG" title="TAG:<$MTTag$>"><$MTTag$></a></li>
  </MTEntryTags>
</ul>


========
SEE ALSO
========

Lastest version of this document will be found:
    http://as-is.net/wiki/Tagwire_Plugin

Advanced documents and Japanese documents are also available from the
above URL.


=======
LICENSE
=======

This code is released under the Artistic License. The terms of the
Artistic License will be found:
    http://www.opensource.org/licenses/artistic-license.php


==================
AUTHOR & COPYRIGHT
==================

Copyright 2005,2006 Hirotaka Ogawa (hirotaka.ogawa at gmail.com)