WordPress Primary Category
====
Select the primary category
https://wordpress.org/plugins/wp-primary-category
- [Installation](#installation)
- [Settings](#settings)
- [Selecting](#selecting)
- [Functions](#functions)
- [Filters](#filters)
- [Shortcode](#shortcode)
- [WP_Query](#wp_query)
- [REST API](#rest-api)
- [To Do](#to-do)
Installation
====
1. Copy the `wp-primary-category` folder into your `wp-content/plugins` folder
2. Activate the `WordPress Primary Category` plugin via the plugin admin page
Settings
====
**How to able the primary category feature?**
1. Open the settings page ( To open that page, we have to two alternatives );
2. Select the taxonomies what you want to able the feature;
3. After selected all taxonomies, click in the save button.
**First Alternative:**
Settings > Primary Category
**Second Alternative:**
Plugins admin page > Settings link in WordPress Primary Category
**Settings Page**
Selecting
====
After edit your settings, now you can select which will be your primaries categories.
Functions
====
| Name | Argument(s) |
|------|-------------|
| get_primary_categories | mixed ( int, WP_Post, NULL ) **$post**
*required*
--
string **$output**
*default value:* OBJECT
*others values:* OBJECT, ARRAY_A, ARRAY_N or "ID"
*optional* |
| get_primary_category | mixed ( int, WP_Term, object, string ) **$taxonomy**
*required*
--
mixed ( int, WP_Post, NULL ) **$post**
*default value:* NULL
*optional*
--
string **$output**
*default value:* OBJECT
*others values:* OBJECT, ARRAY_A, ARRAY_N or "ID"
*optional* |
| the_primary_category | mixed ( int, WP_Term, object, string ) **$taxonomy**
*required*
--
mixed ( int, WP_Post, NULL ) **$post**
*default value:* NULL
*optional*
--
string **$output**
*default value:* "link"
*others values:* "name"
*optional*--
string **$echo**
*default value:* true
*optional* |
| is_primary_category | mixed ( int, WP_Term, object ) **$term**
*required*
--
mixed ( string, NULL ) **$taxonomy**
*default value:* NULL
*optional*
--
mixed ( int, WP_Post, NULL ) **$post**
*default value:* NULL
*optional* |
| has_primary_category | mixed ( int, WP_Post, NULL ) **$post**
*default value:* NULL
*optional* |
**Basic example**
```PHP
$args = array(
'post_type' => 'book',
);
$query = new WP_Query( $args );
if ( $query->have_posts() ) {
echo '';
while ( $query->have_posts() ) {
$query->the_post();
echo '- ' . get_the_title();
if ( has_primary_category() ) {
echo ' - ';
the_primary_category( 'genre' );
}
echo '
';
}
echo '
';
wp_reset_postdata();
}
```
Filters
====
| Filter | Argument(s) |
|--------|-------------|
| wp_primary_category_update_option | array **$data**
mixed ( array, boolean, NULL ) **$option** |
| wp_primary_category_option | array **$data** |
| wp_primary_category_not_allowed_post_types | array **$post_types** |
| wp_primary_category_post_types_args | array **$args** |
| wp_primary_category_post_types | mixed ( array, boolean ) **$post_types** |
| wp_primary_category_not_allowed_taxonomies | array **$taxonomies** |
| wp_primary_category_taxonomies_args | array **$args** |
| wp_primary_category_taxonomies | mixed ( array, boolean ) **$taxonomies** |
| wp_primary_category_html | string **$html**
mixed ( int, WP_Term, object, string ) **$taxonomy**
mixed ( int, WP_Post, NULL ) **$post**
string **$output** |
| wp_primary_category_rest_api_output | string ( OBJECT, ARRAY_A, ARRAY_N or "ID" ) **$output**
array **$request** |
| wp_primary_category_rest_api_data | array **$data**
array **$request** |
**How to use the filters?**
See bellow how to exclude **page post type**.
```PHP
add_filter( 'wp_primary_category_post_types', function( $post_types ) {
if ( isset( $post_types['page'] ) ) {
unset( $post_types['page'] );
}
return $post_types;
} );
```
or
```PHP
add_filter( 'wp_primary_category_not_allowed_post_types', function( $post_types ) {
$post_types['page'] = 'page';
return $post_types;
} );
```
Shortcode
====
| Tag | Attribute(s) |
|-----|--------------|
| the_primary_category | mixed ( int, WP_Term, object, string ) **$taxonomy**
*required*
--
mixed ( int, WP_Post, NULL ) **$post**
*default value:* NULL
*optional*
--
string **$output**
*default value:* "link"
*others values:* "name"
*optional* |
#### How to use
```
[wp_primary_category taxonomy="genre"]
```
```
[wp_primary_category taxonomy="genre" post="1"]
```
```
[wp_primary_category taxonomy="genre" post="1" output="name"]
```
WP_Query
====
**See below how get posts with genre primary category**
```PHP
$args = array(
'post_type' => 'book',
'meta_query' => array(
array(
'key' => '_wp_primary_category_genre',
'value' => array( 2, 4 ), // terms id
'compare' => 'IN',
)
),
);
$query = new WP_Query( $args );
if ( $query->have_posts() ) {
while ( $query->have_posts() ) {
$query->the_post();
// your code here
}
}
```
https://codex.wordpress.org/Class_Reference/WP_Query#Custom_Field_Parameters
REST API
====
**Endpoint**:
`/wp-json/wp/v2/posts/1`
**Default answer:**
```JSON
{
"id": 1,
"title": {
"rendered": "Hello world!"
},
...
"primary_categories": {
"category": 1,
"genre": 2
},
...
}
```
**Use the filter below to change the answer:**
```PHP
add_filter( 'wp_primary_category_rest_api_data', function( $data ) {
if ( isset( $data['genre'] ) ) {
unset( $data['genre'] );
}
return $data;
} );
```
**The new answer:**
```JSON
{
"id": 1,
"title": {
"rendered": "Hello world!"
},
...
"primary_categories": {
"category": 1
},
...
}
```
**Use the filter below to change the output:**
```PHP
add_filter( 'wp_primary_category_rest_api_output', function() {
return OBJECT; // OBJECT, ARRAY_A, ARRAY_N or 'ID'
} );
```
**The new answer:**
```JSON
{
"id": 1,
"title": {
"rendered": "Hello world!"
},
...
"primary_categories": {
"category": {
"term_id": 1,
"name": "My category",
"slug": "my-category",
"term_group": 0,
"term_taxonomy_id": 2,
"taxonomy": "category",
"description": "",
"parent": 0,
"count": 1,
"filter": "raw"
}
},
...
}
```
To Do
====
- add support to Gutenberg ( block editor )