Add-on, ExpressionEngine, Categories

Catman

Robust category display with entry counts and easy to create navs, for use with EE’s native categories

Buy Now

Installation

Move the appropriate catman folder to your system/user/addons folder. And install as a normal EE addon.

If you are using the EE5 version, rename catman-ee5 to catman.

** NOTE: With the release of EE7, the EE5 version of Catman will no longer receive updates past version 1.0.3 **

Usage

Catman acts as a tag pair in your EE templates.

{exp:catman:get}
    {if catman:no_results}
        No results
    {/if}
    Count: {catman:count}
    {catman:categories}
        {category_name}
    {/catman:categories}
{/exp:catman:get}

Catman Params

show

show="4|7"

With this parameter, you can specify which categories will be included in the list. For instance, if you wanted to keep a particular category from being listed you could specify only those you wanted displayed to be included. Category IDs are separated by the pipe character to specify more than one category. If you specify a child category be shown, you must also include its parent category to be shown.

You may alternatively specify which categories to not show

show="not 3|6|8"

If you specify that a parent category is not shown, then any children of that parent category are then unable to be shown by the tag. The parent category is required for any and all children categories.

channel

channel="channel_name"

The name (short name) of the channel that the categories are assigned to. This variable is required unless you only have a single channel. Multiple channels may also be specified.

parent_only

parent_only="y"

Display parent categories only

show_empty

show_empty="y"

This parameter determines whether or not categories that contain no entries for the specific channel are displayed. If you set the parameter to “no” then categories which do not contain entries will not be included in the list.

By default, categories with no entries are included.

depth

depth="2"

Gets nested children of parent categories to the maximum depth set. Defaults to showing all children, regardless of depth.

entry_count

entry_count="y"

Include entry count in parameters.

entry_id

entry_id="123"

Display categories related to the specified entry.

group_id

Alias for category_group

category_group

category_group="2"

Category Groups are specified by ID number (the ID number of each category group is displayed in the Control Panel). The reason we use the ID is because category groups can be called anything (with spaces, quotes, etc.), and also renamed. It would be much more difficult to have to update the tag parameters every time you updated a category name.

And as with many other parameters, you can stack category groups

category_group="1|2|4"

Or use “not” to exclude categories

category_group="not 2"

limit

limit="3"

Limits number of returned categories

orderby / sort

orderby="category_id" sort="asc"

The orderby parameter sets the display order of the entries. Sort sets the direction.

backspace

backspace="7"

The backspace= parameter will remove characters, including spaces and line breaks, from the last iteration of the tag pair:

For example, if you use a
element after each entry, Catman will output this markup:

Category 1

Category 2

Category 3

However, you may not want the
element after the last entry. Count the number of characters, including spaces and line breaks and use the result as the value for the parameter. The example
element includes 6 characters and a line break, for a total of 7:

{exp:catman:get backspace="7"}
    {catman:categories}
        {category_name}

    {/catman:categories}
{/exp:catman:get}

Using backspace=, Catman will output this markup:

Category 1

Category 2

Category 3

cache_ttl

cache_ttl="3600"

By default, Catman will cache calls made, organized by the set params on the tag. Use cache_ttl to set the amount of seconds to keep this cache. Default is 86400 (1 day).

cache

cache="y"

Set to y to cache calls. Defaults to no, so calls are not cached (new in version 1.1.0)

Additional Params

These params can be params or included in query strings

as_json
no_cache

Entry Count

In order to initialize the Entry Count, there are two crucial steps.

Run the Action URL associated with the Count All action (i.e. https://example.com/admin.php?/cp/addons/settings/catman). This may take a bit depending on the number of categories, but is not a destructive action, so can be run any number of times.
Catman assumes that your get tags will include all of the channel information you want to get. If you are using a category in multiple channels, ensure that you include the channel= parameter on your tag with the channel name or names, separated by pipes (|), i.e. {exp:catman:get category_group="3" channel="blog"}

Ongoing Counts

There are two important ongoing entry counting elements that can be done here.

Action URLs

Catman comes with a number of action URLs to process entry counts on your timing.

Extension Hooks

Catman, by default

This call can be expensive when your CMS has a ton of entries. If you would like to turn this off, include the following in your EE config.php file:

$config['catman_ignore_count_hooks'] = true;

Data Shapes

Example Template

{exp:catman:get category_group="3" channel="blog"}
    {if catman:no_results}
        <h1>NO RESULTS</h1>
    {if:else}
        <h1>FOUND {catman:count} RESULTS!</h1>
        {catman:categories}
            <h2>category_name: {category_name}</h2>
            <p>category_id: {category_id}</p>
            <p>parent_id: {parent_id}</p>
            <p>group_id: {group_id}</p>
            <p>category_description: {category_description}</p>
            <p>category_image: {category_image}</p>
            <p>category_url_title: {category_url_title}</p>
            <p>category_order: {category_order}</p>
            <p>Custom Field: {test_text}</p>
            <h3>Simple Path:</h3>
            {simple_path}/{simple_path:uri}{/simple_path}
            <h3>Counts:</h3>
            <p>child_count: {child_count}</p>
            {entry_count}
                <p>entry_count:count: {entry_count:count}</p>
                <p>entry_count:parent_count: {entry_count:parent_count}</p>
                <p>entry_count:child_count: {entry_count:child_count}</p>
                <p>entry_count:count_with_parent: {entry_count:count_with_parent}</p>
                <p>entry_count:count_with_children: {entry_count:count_with_children}</p>
            {/entry_count}
            <h3>Parent:</h3>
            {parent}
                <p>category_name: {parent:category_name}</p>
                <p>category_id: {parent:category_id}</p>
                <p>parent_id: {parent:parent_id}</p>
                <p>group_id: {parent:group_id}</p>
                <p>category_description: {parent:category_description}</p>
                <p>category_image: {parent:category_image}</p>
                <p>category_url_title: {parent:category_url_title}</p>
                <p>category_order: {parent:category_order}</p>
            {/parent}
            {children}
                <h3>CHILD: {child:category_name}</h3>
                <p>category_id: {child:category_id}</p>
                <p>parent_id: {child:parent_id}</p>
                <p>group_id: {child:group_id}</p>
                <p>category_description: {child:category_description}</p>
                <p>category_image: {child:category_image}</p>
                <p>category_url_title: {child:category_url_title}</p>
                <p>category_order: {child:category_order}</p>
            {/children}
        {/catman:categories}
    {/if}
{/exp:catman:get}

Categories from Segments

Catman also allows you to get category information, parsed early, to help you get access to category information from URL segment information.

catman_segment_n_category_id

{catman_segment_n_category_id}

Get category ID of segment N (representing the segment of the URL you would like to get). Returns the data shape above, or null if not found.

catman_segment_n_category_name

{catman_segment_n_category_name}

Get category Name of segment N (representing the segment of the URL you would like to get). Returns the data shape above, or null if not found.

catman_segment_n_category_description

{catman_segment_n_category_description}

Get category description of segment N (representing the segment of the URL you would like to get). Returns the data shape above, or null if not found.

catman_segment_n_category_image

{catman_segment_n_category_image}

Get category image of segment N (representing the segment of the URL you would like to get). Returns the data shape above, or null if not found.

catman_segment_n_category_parent_id

{catman_segment_n_category_parent_id}

Get parent ID of segment N (representing the segment of the URL you would like to get). Returns the data shape above, or null if not found.

catman_segment_n_category_group_id

{catman_segment_n_category_group_id}

Get category group ID of segment N (representing the segment of the URL you would like to get). Returns the data shape above, or null if not found.

catman_last_segment_category_id

{catman_last_segment_category_id}

Get category ID of the last segment of the URL. Returns the data shape above, or null if not found.

catman_last_segment_category_name

{catman_last_segment_category_name}

Get category name of the last segment of the URL. Returns the data shape above, or null if not found.

catman_last_segment_category_description

{catman_last_segment_category_description}

Get category description of the last segment of the URL. Returns the data shape above, or null if not found.

catman_last_segment_category_image

{catman_last_segment_category_image}

Get category image of the last segment of the URL. Returns the data shape above, or null if not found.

catman_last_segment_category_parent_id

{catman_last_segment_category_parent_id}

Get category parent ID of the last segment of the URL. Returns the data shape above, or null if not found.

catman_last_segment_category_group_id

{catman_last_segment_category_group_id}

Get category group ID of the last segment of the URL. Returns the data shape above, or null if not found.

catman_segment_category_ids

{catman_segment_category_ids}

Create inclusive stack of all category ids present in segments, separated by &

catman_segment_category_ids_piped

{catman_segment_category_ids_piped}

Create inclusive stack of all category ids present in segments, separated by |

Credits

Logo by Emilee Black!