<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
<document>
    <header>
        <title>Associated Categories plugin</title>
    </header>

    <body>
        <section>
            <title>description</title>
            <p>
                This plugin will look for blog entry meta-data under the key, "categories". This
                meta-data must be a comma-separated list of blog categories that are to be
                associated with the blog entry. In its current form, this plugin creates associated
                categories that are backed by the filesystem.
            </p>

        </section>
        <section>
            <title>installation and setup</title>
            <p>
                In your global
                <code>plugin.properties</code> file, add the following line:
            </p>
            <source>
                associated-categories=org.blojsom.plugin.meta.AssociatedCategoriesPlugin
            </source>

            <p>
                You may then add "associated-categories" <strong>after</strong>
                a plugin such as the meta-plugin which would populate an entry's meta-data. This
                plugin does not necessarily need to be after any specific plugin, but the meta-data
                plugin can be used to populated a blog entry's meta-data from meta-data in the blog
                entry after which this plugin can take advantage of categories in the meta-data.
                "associated-categories" must be added in the individual user's <code>plugin.properties</code>
                file.
            </p>
            <source>
                html.blojsom-plugin-chain=meta,...,associated-categories
            </source>

        </section>
        <section>
            <title>usage and URL parameters</title>

            <section>
                <title>usage and URL parameters</title>
                <p>
                    This plugin works by looking in the blog entry meta-data for information under
                    the key "categories". There are no URL parameters which control the operation of this
                    plugin.
                </p>
            </section>
            <section>
                <title>context attributes and types</title>
                <p>
                    The following table describes the context attributes that are available and their associated type.
                </p>
                <table>
                    <tr>
                        <th>Context key</th>
                        <th>Input or Output</th>
                        <th>Type</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td>BLOJSOM_PLUGIN_ASSOCIATED_CATEGORIES</td>
                        <td>Output</td>
                        <td>
                            <code>org.blojsom.blog.BlogCategory[]</code>
                        </td>
                        <td>
                            <code>BlogCategory</code> objects will be constructed from the associated categories
                            and populated back out as an array of objects. You can then check for the existence
                            of this key in the context object available from your page template.
                        </td>
                    </tr>
                </table>

            </section>
        </section>
    </body>
</document>

