ExpressionEngine Docs

# ExpressionEngine Channel Categories API

## Calling the Class

The Channel Category class is called with the `api->instantiate()` function:

    ee()->load->library('api');
    ee()->legacy_api->instantiate('channel_categories');

## Function Reference

class `Api_channel_categories`

- `category_tree($group_id[, $selected = ''[, $order = '']])`
- `category_form_tree([$nested = 'y'[, $categories = FALSE[, $sites = FALSE]]])`
- `fetch_category_parents($cat_array)`
- `fetch_allowed_category_groups($cat_group)`

### `category_tree($group_id[, $selected = ''[, $order = '']])`

Parameter | Type | Description
--- | --- | ---
$group_id | `Mixed` | Category group ID, pipe delimited string of category group IDs or array of category group IDs to create a category tree for
$selected | `Mixed` | Category ID, pipe delimited string of category IDs or array of category IDs to mark as selected
$order | `String` | `c` for custom ordering, `a` for alphabetical
Returns | `Array/Boolean` | `FALSE` if no results, otherwise an associative array containing the category tree (see below)

This function returns an array consisting of a hierarchy tree of categories. It has one required parameter, the category `group_id`. The category group(s) may be defined as a pipe delimited list of `group_ids` or an array. The second parameter allows the specification of any selected categories (useful when used as form data), while the third parameter determines the ordering of the categories (`a` for alphabetical based on `category_name` or `c` for the specified custom ordering):

    ee()->api_channel_categories->category_tree(
        (mixed) $group_id, [(mixed) $selected, [(string) c or a]]
    );

Example of returned data:

    array(
        0 => array(
            '0' =>  (int) Category ID,
            '1' =>  (string) Category Name,
            '2' =>  (int) Category Group ID,
            '3' =>  (string) Category Group Name,
            '4' =>  (bool) Selected,
            '5' =>  (int) Depth Nested in the Tree,
            '6' =>  (int) Category Parent ID
        ),
        1 => array(...)
    );

### `category_form_tree([$nested = 'y'[, $categories = FALSE[, $sites = FALSE]]])`

Parameter | Type | Description
--- | --- | ---
$nested | `String` | y if you want the array to be nested, anything else will return a flat listing
$categories | `Mixed` | Category ID, pipe delimited string of category IDs, or array of Category IDs
$sites | `Mixed` | Site ID, pipe delimited string of site IDs, or array of site IDs
Returns | `Array` | Array consisting of a hierarchy tree of categories formatted for use in select and multi-select forms and related javascript

This function returns an array consisting of a hierarchy tree of categories formatted for use in select and multi-select forms and related javascript. It takes 3 optional parameters. The first parameter determines whether the returned categories are arranged in a nested format. The second parameter allows you to specify categories to include or exclude from the array. Included categories may be in the format of an array of category ids. You may also include or exclude categories using a pipe delimited string. This parameter defaults to `(bool) FALSE`, which will include all categories. The third parameter determines the `site_id`, and may be in the format of an array of site ids. You may also include or exclude sites using a pipe delimited string. This parameter defaults to `(bool) FALSE`, which will include only categories from the current site:

    ee()->api_channel_categories->category_form_tree(
        [(string) $nested y/n, [(mixed) $categories, [(mixed) $sites]]]
    );

Example of returned data:

    array(
        0 => array(
            '0' =>  (int) Category Group ID,
            '1' =>  (int) Category ID,
            '2' =>  (string) Category Name in ASCII Format,
            '3' =>  (int) Parent ID
        ),
        1 => array(...)
    );

### `fetch_category_parents($cat_array)`

Parameter | Type | Description
--- | --- | ---
$cat_array | `Array` | Array of category IDs
Returns | `Void` |

This function finds the parents of the specified categories and adds them to the `cat_parents` class variable:

    ee()->api_channel_categories->fetch_category_parents(
        (array) $cat_array
    );

### `fetch_allowed_category_groups($cat_group)`

Parameter | Type | Description
--- | --- | ---
$cat_group | `Mixed` | Category ID, or an array or pipe delimited string of category IDs
Returns | `Array/Boolean` | Array of category group names the user has permission to administrate or `FALSE` if there are no allowed category groups.

Given an array or a pipe delimited list of category group ids, this returns an array of the category group names if the user has permission to administrate channels or edit categories. Returns `FALSE` otherwise:

    ee()->api_channel_categories->fetch_allowed_category_groups(
        (mixed) $cat_group
    );

Example Usage:

    $group_id = '1|5';

    $allowed = ee()->api_channel_categories->fetch_allowed_category_groups($group_id);

    if ($allowed != FALSE) {
        foreach($allowed as $val)
        {
            echo 'Group ID: '.$val['0'].' Group Name: '.$val['1'].'';
        }
    }