Listing Categories

Functions for working with listing categories (taxonomies that group listing attribute terms).

See the Category object reference for all methods available on the returned object.

---

Functions

dms_get_category( int|string $category, int $type_id = 0 ): Category

Retrieves a single listing category by ID or slug. Optionally scoped to a specific type. If you are using a slug for the category parameter then type_id is highly recommended to avoid retrieving matching category from a different listing type.

Parameters

Name	Type	Default	Description
$category	int\|string	-	The category ID or slug
$type_id	int	0	Optional type ID to scope slug lookups

Returns - Category

Example

// By ID
$category = dms_get_category( 3 );

// By slug
$category = dms_get_category( 'make' );

echo esc_html( $category->get( 'singular' ) );

---

dms_get_all_categories( array $args = [] ): array

Returns all registered listing categories, optionally filtered by the provided args.

Parameters

Name	Type	Default	Description
$args	array	[]	Filter args passed to Categories::filter_categories()

Returns - Category[]

Example

$categories = dms_get_all_categories();

foreach ( $categories as $category ) {
    echo esc_html( $category->get( 'plural' ) );
}

// Filtered to a specific type
$categories = dms_get_all_categories( [ 'type_id' => 1 ] );

---

dms_add_category( array $category_data ): int|bool

Creates a new listing category. Returns the new category ID on success, false on failure.

Parameters

Name	Type	Default	Description
$category_data	array	-	Category data. Required keys: singular, plural. Optional: settings.

Returns - int\|bool

Example

$category_id = dms_add_category( [
    'singular' => 'Make',
    'plural'   => 'Makes',
] );

---

dms_delete_category( int $category_id ): bool

Deletes a listing category and all of its associated terms.

Parameters

Name	Type	Default	Description
$category_id	int	-	The category ID to delete

Returns - bool

Example

$deleted = dms_delete_category( 3 );

---

dms_get_current_category(): bool|Category

Returns the category being edited on the current admin screen. Returns false if no category context is available.

Returns - Category or false

Example

$category = dms_get_current_category();

if ( $category && $category->exists() ) {
    echo esc_html( $category->get( 'singular' ) );
}

---

dms_add_category_tab( array $tab_data ): void

Registers a custom options tab that appears on the listing category settings page.

Parameters

Name	Type	Default	Description
$tab_data	array	-	Tab definition including id, title, icon, and fields keys

Returns - void

Example

dms_add_category_tab( [
    'id'     => 'my-category-settings',
    'title'  => 'My Settings',
    'icon'   => 'settings',
    'fields' => [
        'my_field' => [
            'id'   => 'my_field',
            'type' => 'text',
            'name' => 'Custom Field',
        ],
    ],
] );

---

dms_add_filterable_category_data( Category $category ): void

Registers a category as filterable, making it available in the front-end filter system.

Parameters

Name	Type	Default	Description
$category	Category	-	The category to register as filterable

Returns - void

Example

$category = dms_get_category( 'make' );
dms_add_filterable_category_data( $category );

---

dms_get_filterable_category_data(): array

Returns all categories that have been registered as filterable (e.g. by widgets or shortcodes).

Returns - array

Example

$filterable = dms_get_filterable_category_data();