Function and usage of add_users_page() in wordpress

Question

Answers ( 1 )

    0
    2024-01-05T12:57:59+00:00

    The add_users_page() function in WordPress is used to add a submenu page to the Users/Profile main menu in the WordPress admin panel. This function is particularly useful for plugin developers who want to add additional options or settings related to user management.

    Function Signature:

    add_users_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $callback = '', int $position = null ): string|false
    

    Detailed Explanation:

    Parameters:

    1. $page_title (string, required):

      • This is the text that will be displayed in the title tags of the page when the menu is selected. It's typically a more descriptive title of the page.
    2. $menu_title (string, required):

      • The text used for the menu item itself. This is usually a shorter, more concise title.
    3. $capability (string, required):

      • This parameter specifies the capability required for this menu to be displayed to the user. Capabilities are used in WordPress to determine what a user can and cannot do. For instance, 'manage_options' is a capability typically reserved for administrators.
    4. $menu_slug (string, required):

      • This is a unique identifier for the menu. It's used in URLs and internally by WordPress to identify this specific menu item.
    5. $callback (callable, optional):

      • A function that is called to output the content for this page. When a user clicks on the menu item, this function is executed to display the page content.
      • Default is an empty string, which means no function is called.
    6. $position (int, optional):

      • Specifies the position in the menu order where this item should appear.
      • Default is null, which lets WordPress decide the position.

    Return Value:

    • string|false
      • The function returns the resulting page’s hook_suffix if the user has the required capability. This hook_suffix can be used to further manage the page, like enqueueing scripts or styles specifically for this page.
      • Returns false if the user does not have the required capability.

    Sample Usage:

    Here’s an example of how you might use add_users_page():

    function my_custom_user_page() {
        // Page content goes here
        echo '<h1>My Custom User Page</h1>';
        echo '<p>Welcome to the custom user page!</p>';
    }
    
    function add_my_custom_user_page() {
        add_users_page(
            'My Custom User Page', // Page title
            'Custom User Page',    // Menu title
            'manage_options',      // Capability
            'my-custom-user-page', // Menu slug
            'my_custom_user_page'  // Callback function
        );
    }
    
    add_action('admin_menu', 'add_my_custom_user_page');
    

    In this example, a new submenu page titled "Custom User Page" is added under the Users/Profile main menu. It’s only accessible by users who have the 'manage_options' capability (typically administrators). When this menu item is clicked, it calls the my_custom_user_page function, which outputs the content of the page.

Leave an answer