DEV Community: Amit Biswas

Custom post type capabilities and roles in WordPress

Amit Biswas — Tue, 08 Sep 2020 11:04:17 +0000

We often use custom post types for various purposes. I believe all WordPress plugin developers love this feature. But many of us who are relatively new in WordPress development, probably not aware of custom capabilities and it's potentials. In this article, I will try to put some light on custom post type capabilities.

Why use new capabilities for custom post type

The heart of the question is why I should use new capabilities instead of the defaults. The answer is simple. Whenever you need precise control for different users, you need custom capabilities. For example, if your plugin have custom post types and you want to distribute specific tasks to different users, you need custom capabilities.

Let's say I have a post type book and only authors can create, edit books. I will assign custom capabilities to authors only. There is a brilliant plugin available to customize user roles and capabilities. It's called "User Role Editor". By default, WordPress assigns capabilities based on the user roles such as "admin", "editor", "author" and so on. To know about user role based capabilities, use get_role() function.

How to create new capabilities

Now that we have understood the potentials, let's see how we can create. When we register a new post type in a plugin, we can define custom capabilities.

A custom post type needs to be registered with register_post_type() function and init action hook. For example, let's register a book post type with custom capabilities -

function book_post_type() {
    $args = array(
        'public'          => true,
        'label'           => __( 'Books', 'textdomain' ),
        'menu_icon'       => 'dashicons-book',
        'show_in_rest'    => true,
        'taxonomies'      => array( 'category' ),
        'capability_type' => array('book','books'), //custom capability type
        'map_meta_cap'    => true, //map_meta_cap must be true
    );
    register_post_type( 'book', $args );
}
add_action( 'init', 'book_post_type' ); //action hook

If you notice, we have used 'capability_type' => array('book','books') which will create new capability type for the book post type. It is also important to use 'map_meta_cap' => true, for custom post types. If you don't set it true, WordPress will not be able to map new capabilities. Default capability keys are -

/**
 * Default capability type keys
 * Will be mapped with our types which are "book"(singular), "books"(plural)
 */

[edit_post]              => edit_book
[read_post]              => read_book
[delete_post]            => delete_book
[edit_posts]             => edit_books
[edit_others_posts]      => edit_other_books
[publish_posts]          => publish_books
[read_private_posts]     => read_private_books
[delete_posts]           => delete_books
[delete_private_posts]   => delete_private_books
[delete_published_posts] => delete_published_books
[delete_others_posts]    => delete_others_books
[edit_private_posts]     => edit_private_books
[edit_published_posts]   => edit_published_books

The restrictions

Now at this point, WordPress will not show the custom post type (book) for any logged in user. This is for security purposes. As we have added new capabilities, we need to tell WordPress which user have these capabilities.

Add newly added capabilities for admin

Admin users are at the top level with all default capabilities assigned to them. So admin users also should have all custom capabilities. Let's do that in an efficient way.

Role based capability can be added by the WP_Role::add_cap( string $cap ) function. This is important that we hook this function on plugin or theme activation. We shall use a class based static methods for better code management. We need to add the following code to the main plugin file.

// add custom capabilities to the admin on plugin activation
register_activation_hook( __FILE__, array( 'Admin_Roles', 'add_admin_capabilities' ) );

The main class for admin role

/**
 * Main class for ADMINISTRATOR
 */
class Admin_Roles {
    /**
     * Custom capabilities of custom post types
     */
    private static $customCaps = array(
        [ 'singular' => 'book', 'plural' => 'books' ],
    );

    /**
     * Add custom capabilities for admin
     */
    public static function add_admin_capabilities() {

        $role = get_role( 'administrator' );

        foreach( self::$customCaps as $cap ){
            
            $singular = $cap['singular'];
            $plural = $cap['plural'];

            $role->add_cap( "edit_{$singular}" ); 
            $role->add_cap( "edit_{$plural}" ); 
            $role->add_cap( "edit_others_{$plural}" ); 
            $role->add_cap( "publish_{$plural}" ); 
            $role->add_cap( "read_{$singular}" ); 
            $role->add_cap( "read_private_{$plural}" ); 
            $role->add_cap( "delete_{$singular}" ); 
            $role->add_cap( "delete_{$plural}" );
            $role->add_cap( "delete_private_{$plural}" );
            $role->add_cap( "delete_others_{$plural}" );
            $role->add_cap( "edit_published_{$plural}" );
            $role->add_cap( "edit_private_{$plural}" );
            $role->add_cap( "delete_published_{$plural}" );
            
        }

    }

}

Now that we have our class ready, we can add any number of post type capabilities for admin. We just need to add capability types to private static $customCaps variable. For example, a newly added custom post type capability can be added like this -

private static $customCaps = array(
    [ 'singular' => 'book', 'plural' => 'books' ],
    [ 'singular' => 'story', 'plural' => 'stories' ],
);

Deactivate and reactivate the plugin

As we have used register_activation_hook() function, you need to deactivate and then reactivate the plugin to make this code work. The activation hook will add all the new capabilities for the admin. From this point, you may use the "User Role Editor" plugin and control user roles and assign custom post type capabilities for them.

Conclusion

All custom post types should have custom capability types as it gives the power to the plugin users. This particular method is very simple and manageable. I use this method for all of my plugins that registers custom post types.

I hope you enjoyed this article and if you have any question, please ask in the comment section.

Philosophy Quiz - A JavaScript Project

Amit Biswas — Wed, 08 Jul 2020 09:54:55 +0000

This is an example project of JavaScript. This project creates and evaluates results of a quiz which is purely object based. All the JavaScript code is well documented and commented for better understanding of practical JS use.

Cover image by Cdd20 from Pixabay

Get categories by post type in WordPress

Amit Biswas — Fri, 22 May 2020 11:35:15 +0000

Have you ever wondered about how to get categories by post type? Categories is the default taxonomy for WordPress just like the tags. But categories have hierarchies and tags don't have. Categories are used for the posts by default. However, if we register a new custom post type for which we wish to add categories, it's fairly simple job to do.

Registering a new post type is a plugin functionality and we should always do it by creating a custom plugin. You may find the developers documentation for registering a custom post type here.

Practical scenario

Let's say we have a custom post type "movies" which also shares the category with the posts. Now, we have categories "comedy", "horror" and "adventure" for the movies posts and "stories", "interviews", "reviews" for the default posts. So, for both of the archives we want to show only those categories that relates to the post type itself.

The issues

There are several ways to get categories in WordPress. The get_categories() function will retrieve all the categories available in your site regardless of post type. Similarly wp_list_categories() and get_terms() can also fetch and display categories or terms. But none of them have the option to retrieve categories for a given post type.

Our goal to achieve

In this tutorial we shall discover how we can get categories by post type. In our test case, the movies posts archive will show only "comedy", "horror" and "adventure" and the default posts archive will show "stories", "interviews", "reviews". Let's see how we shall do it.

Coding plans

To achieve this, we have to think in a different way. WordPress functions covers everything that you need to do in a development. We shall explore some of the functions for this.

The get_posts() function retrieve posts array which includes post ID. The get_the_terms() function retrieves the terms of the taxonomy that are attached to the post. Now, we have something to start with. Our approach will be to make a function which will do -

Get all posts with get_posts() function.
Then loop through the posts array and retrieve the terms attached to those posts with get_the_terms() function.
Store the new terms objects within a new array.
Use the new array and loop through to make a new array of terms with our desired key, value pair.
Finally, make that array unique as duplicate entries can be there.
Return the final array.

The code snippet to get categories by post type

Here is the full snippet that will retrieve categories or custom taxonomy terms by post type. You may place it in your theme's function.php.

if( !function_exists('tartist__get_terms_by_post_type') ){

    function tartist__get_terms_by_post_type( $postType = 'post', $taxonomy = 'category'){

        /**
         * Get Terms by post type
         * @author Amit Biswas
         * 
         * @param postType default 'post'
         * @param taxonomy default 'category'
         * 
         * @return array of terms for a given $posttype and $taxonomy
         * @since 1.0.1
         * 
         * 1. Get all posts by post type
         * 2. Loop through the posts array and retrieve the terms attached to those posts
         * 3. Store the new terms objects within `$post_terms`
         * 4. loop through `$post_terms` as it's a array of term objects.
         * 5. store the terms with our desired key, value pair inside `$post_terms_array`
         */

        //1. Get all posts by post type
        $get_all_posts = get_posts( array(
            'post_type'     => esc_attr( $postType ),
            'post_status'   => 'publish',
            'numberposts'   => -1
        ) );

        if( !empty( $get_all_posts ) ){

            //First Empty Array to store the terms
            $post_terms = array();
            
            //2. Loop through the posts array and retrieve the terms attached to those posts
            foreach( $get_all_posts as $all_posts ){

                /**
                 * 3. Store the new terms objects within `$post_terms`
                 */
                $post_terms[] = get_the_terms( $all_posts->ID, esc_attr( $taxonomy ) );

            }

            //Second Empty Array to store final term data in key, value pair
            $post_terms_array = array();

            /**
             * 4. loop through `$post_terms` as it's a array of term objects.
             */

            foreach($post_terms as $new_arr){
                foreach($new_arr as $arr){

                    /**
                     * 5. store the terms with our desired key, value pair inside `$post_terms_array`
                     */
                    $post_terms_array[] = array(
                        'name'      => $arr->name,
                        'term_id'   => $arr->term_id,
                        'slug'      => $arr->slug,
                        'url'       => get_term_link( $arr->term_id )
                    );
                }
            }

            //6. Make that array unique as duplicate entries can be there
            $terms = array_unique($post_terms_array, SORT_REGULAR);

            //7. Return the final array
            return $terms;

        }

    }

}

The function tartist__get_terms_by_post_type() accepts 2 parameters. First parameter is for the post type, second parameter is for taxonomy. Both parameters are optional as the default value is set to post and category.

Return value

On success, this function returns the terms array for the given post type and taxonomy. Here is an example -

//store the categories for movies post type
$postTerms = tartist__get_terms_by_post_type('movies');
var_dump( $postTerms );

The above code will return the categories for movies. As per our example -

array (size=3)
    0 => 
        array (size=4)
        'name'    => string 'Comedy' (length=6)
        'term_id' => int 7
        'slug'    => string 'comedy' (length=6)
        'url'     => string 'http://example.com/category/comedy/' (length=35)
    1 => 
        array (size=4)
        'name'    => string 'Horror' (length=6)
        'term_id' => int 9
        'slug'    => string 'horror' (length=6)
        'url'     => string 'http://example.com/category/horror/' (length=35)
    2 => 
        array (size=4)
        'name'    => string 'Adventure' (length=9)
        'term_id' => int 10
        'slug'    => string 'adventure' (length=9)
        'url'     => string 'http://example.com/category/adventure/' (length=38)

How to use

There are many scopes where you can use this function. For instance, you can create a new widget that shows the categories by post type. Or you may use this to create interactive forms etc. It's totally up to you, how you will use this in your project.

For example, let's create an unordered list of terms with this -

<ul>
<?php
    //store the categories for movies post type
    $postTerms = tartist__get_terms_by_post_type('movies');
    
    if( !empty( $postTerms ) ){
        foreach( $postTerms as $term ){ 
?>
    <li><a href="<?php echo esc_url( $term['url'] ); ?>><?php echo esc_html( $term['name'] ); ?></a></li>
<?php } } ?>
</ul>

Special note

If you check our main function, at point 5 where we are making the $post_terms_array array, you can add anything that is relevant to terms. Here we have added the term archive url parameter which is not originally returned by the get_the_terms() function.

I hope you enjoyed the tutorial and if you find it helpful, I will appreciate if you share the article with others too. Thank you all.

Featured image by Martin Shreder on Unsplash

How to create a WordPress posts archive with REST API and ajax - A practical example

Amit Biswas — Thu, 14 May 2020 11:14:05 +0000

In this tutorial, we shall learn about a different approach of making posts archive in a WordPress site. Instead of the default WordPress loop or WP_Query(), we will be using WordPress REST API and jQuery Ajax. Here's the codepen that we shall try to achieve. You can find the full tutorial here - WordPress posts archive with REST API and ajax.

Retrieve WordPress posts array with ID and title

Amit Biswas — Mon, 04 May 2020 07:21:50 +0000

Introduction

As a WordPress developer, I often feel the need for post title and post ID together. It seems easy task using the available WordPress function like get_the_title(). But outside the loop that only works if you know the post ID. However, what if we want to retrieve all posts title with ID? Or posts by category etc?

I will show you a powerful way to do that and store our data inside an array with $key=>$value settings and for this I will use the native WordPress function called "get_posts()".

Where to write

Any code snippet can be written directly in your theme's "functions.php" file or if you are writing a plugin, you may place it inside your main plugin file. Though if you have many snippets for your project, you may place the code inside a separate PHP file and then you can call the file inside the functions.php using the require() function.

Code snippet

/**
 * Retrieve posts
 * @param post_type
 * (string|array) A post type slug (string) or array of post type slugs. Default 'post'.
 * @param total_posts
 * (int) The number of posts to query for. Use -1 to request all posts. Default 10.
 * @param order
 * (string) Designates ascending or descending order of posts. 
 * Default 'DESC'. Accepts 'ASC', 'DESC'.
 * 
 * @return array( key => value )
 */
function tartist__posts_array( $post_type = '', $total_posts = '', $order = '' ){
    
    $get_all_posts = get_posts( array(
        'post_type'     => $post_type ? esc_attr( $post_type ) : 'post',
        'post_status'   => 'publish',
        'numberposts'   => $total_posts ? esc_attr( $total_posts ) : 10,
        'order'     => $order ? esc_attr( $order ) : 'DESC'
    ) );

    $posts = array();

    foreach( $get_all_posts as $newPosts ){
        $posts[$newPosts->ID] = esc_html($newPosts->post_title);
    }

    return $posts;

}

How to use

As you may see, the function tartist__posts_array() accepts 3 parameters and those are optional. If no parameters are given, this function will return the array with default settings. You can call this function in any WordPress template or function. For example, if you paste this code inside your single.php as var_dump( tartist__posts_array() ); it will show you the returned array just like the example below -

array (size=3)
  1 => string 'Title 1' (length=7)
  2 => string 'Title 2' (length=7)
  3 => string 'Title 3' (length=7)
 
  ... and so on

Now, you can easily use this array to extract the values and titles as per your need. You can also use this function to return a custom post type posts. The first parameter will handle that. The second parameter is for total number of posts you want to return and the last parameter is for ordering. I will show you a practical example now.

A practical example of use

Suppose if you need a dynamic drop down select for a form, you can easily do so by using the array like the example below -

$postsArray = tartist__posts_array();

<select>
<?php foreach( $postsArray as $key=>$value ){ ?>
    <option value="<?php echo esc_attr( $key ); ?>" ><?php echo esc_html( $value ); ?></option>
<?php } ?>
</select>

The above code will render a drop down select with options in HTML format like this -

<select>        
    <option value="1">Title 1</option>
    <option value="2">Title 2</option>
    <option value="3">Title 3</option>
</select>

Apart from this, there can be many more usages as you can imagine. It will save a lot of time for your project if you use it in proper place with proper ideas. I have used similar function in one of me free Elementor extension. You can download it from GitHub page.

Let me know if you have more ideas on this function.

Resources

All about get_posts function.

Grid Carousel with "Tiny Slider"

Amit Biswas — Fri, 01 May 2020 07:18:00 +0000

Discover how to create a grid carousel with tiny slider script. Plain JavaScript used to create this carousel as the tiny slider itself using vanilla js. You can use this code in any application like WordPress and create a dynamic grid carousel with it. You can find the tutorial of this pen here: