WordPress.org

Make WordPress Core

Changeset 12914


Ignore:
Timestamp:
01/31/2010 05:36:00 PM (9 years ago)
Author:
westi
Message:

Add phpdoc to all the add_*_page functions.
Rename arguments to empasise that people should be using Capabilities not User Levels and named hooks not FILE.
See #12101.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-admin/includes/plugin.php

    r12913 r12914  
    658658//
    659659
    660 function add_menu_page( $page_title, $menu_title, $access_level, $file, $function = '', $icon_url = '', $position = NULL ) {
     660/**
     661 * Add a top level menu page
     662 *
     663 * This function takes a capability which will be used to determine whether
     664 * or not a page is included in the menu.
     665 *
     666 * The function which is hooked in to handle the output of the page must check
     667 * that the user has the required capability as well.
     668 *
     669 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     670 * @param string $menu_title The text to be used for the menu
     671 * @param string $capability The capability required for this menu to be displayed to the user.
     672 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     673 * @param callback $function The function to be called to output the content for this page.
     674 * @param string $icon_url The url to the icon to be used for this menu
     675 * @param int $position The position in the menu order this one should appear
     676 */
     677function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = NULL ) {
    661678    global $menu, $admin_page_hooks, $_registered_pages;
    662679
    663     $file = plugin_basename( $file );
    664 
    665     $admin_page_hooks[$file] = sanitize_title( $menu_title );
    666 
    667     $hookname = get_plugin_page_hookname( $file, '' );
    668     if (!empty ( $function ) && !empty ( $hookname ) && current_user_can( $access_level ) )
     680    $menu_slug = plugin_basename( $menu_slug );
     681
     682    $admin_page_hooks[$menu_slug] = sanitize_title( $menu_title );
     683
     684    $hookname = get_plugin_page_hookname( $menu_slug, '' );
     685    if (!empty ( $function ) && !empty ( $hookname ) && current_user_can( $capability ) )
    669686        add_action( $hookname, $function );
    670687
     
    675692    }
    676693
    677     $new_menu = array ( $menu_title, $access_level, $file, $page_title, 'menu-top ' . $hookname, $hookname, $icon_url );
     694    $new_menu = array ( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $hookname, $hookname, $icon_url );
    678695
    679696    if ( NULL === $position  ) {
     
    688705}
    689706
    690 function add_object_page( $page_title, $menu_title, $access_level, $file, $function = '', $icon_url = '') {
     707/**
     708 * Add a top level menu page in the 'objects' section
     709 *
     710 * This function takes a capability which will be used to determine whether
     711 * or not a page is included in the menu.
     712 *
     713 * The function which is hooked in to handle the output of the page must check
     714 * that the user has the required capability as well.
     715 *
     716 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     717 * @param string $menu_title The text to be used for the menu
     718 * @param string $capability The capability required for this menu to be displayed to the user.
     719 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     720 * @param callback $function The function to be called to output the content for this page.
     721 * @param string $icon_url The url to the icon to be used for this menu
     722 */
     723function add_object_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '') {
    691724    global $_wp_last_object_menu;
    692725
    693726    $_wp_last_object_menu++;
    694727
    695     return add_menu_page($page_title, $menu_title, $access_level, $file, $function, $icon_url, $_wp_last_object_menu);
    696 }
    697 
    698 function add_utility_page( $page_title, $menu_title, $access_level, $file, $function = '', $icon_url = '') {
     728    return add_menu_page($page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $_wp_last_object_menu);
     729}
     730
     731/**
     732 * Add a top level menu page in the 'utility' section
     733 *
     734 * This function takes a capability which will be used to determine whether
     735 * or not a page is included in the menu.
     736 *
     737 * The function which is hooked in to handle the output of the page must check
     738 * that the user has the required capability as well.
     739 *
     740 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     741 * @param string $menu_title The text to be used for the menu
     742 * @param string $capability The capability required for this menu to be displayed to the user.
     743 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     744 * @param callback $function The function to be called to output the content for this page.
     745 * @param string $icon_url The url to the icon to be used for this menu
     746 */
     747function add_utility_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '') {
    699748    global $_wp_last_utility_menu;
    700749
    701750    $_wp_last_utility_menu++;
    702751
    703     return add_menu_page($page_title, $menu_title, $access_level, $file, $function, $icon_url, $_wp_last_utility_menu);
    704 }
    705 
    706 function add_submenu_page( $parent, $page_title, $menu_title, $access_level, $file, $function = '' ) {
     752    return add_menu_page($page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $_wp_last_utility_menu);
     753}
     754
     755/**
     756 * Add a sub menu page
     757 *
     758 * This function takes a capability which will be used to determine whether
     759 * or not a page is included in the menu.
     760 *
     761 * The function which is hooked in to handle the output of the page must check
     762 * that the user has the required capability as well.
     763 *
     764 * @param string $parent_slug The slug name for the parent menu (or the file name of a standard WordPress admin page)
     765 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     766 * @param string $menu_title The text to be used for the menu
     767 * @param string $capability The capability required for this menu to be displayed to the user.
     768 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     769 * @param callback $function The function to be called to output the content for this page.
     770 */
     771function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
    707772    global $submenu;
    708773    global $menu;
     
    711776    global $_registered_pages;
    712777
    713     $file = plugin_basename( $file );
    714 
    715     $parent = plugin_basename( $parent);
    716     if ( isset( $_wp_real_parent_file[$parent] ) )
    717         $parent = $_wp_real_parent_file[$parent];
    718 
    719     if ( !current_user_can( $access_level ) ) {
    720         $_wp_submenu_nopriv[$parent][$file] = true;
     778    $menu_slug = plugin_basename( $menu_slug );
     779    $parent_slug = plugin_basename( $parent_slug);
     780
     781    if ( isset( $_wp_real_parent_file[$parent_slug] ) )
     782        $parent_slug = $_wp_real_parent_file[$parent_slug];
     783
     784    if ( !current_user_can( $capability ) ) {
     785        $_wp_submenu_nopriv[$parent_slug][$menu_slug] = true;
    721786        return false;
    722787    }
     
    726791    // parent file someone is trying to link back to the parent manually.  In
    727792    // this case, don't automatically add a link back to avoid duplication.
    728     if (!isset( $submenu[$parent] ) && $file != $parent  ) {
     793    if (!isset( $submenu[$parent_slug] ) && $menu_slug != $parent_slug  ) {
    729794        foreach ( (array)$menu as $parent_menu ) {
    730             if ( $parent_menu[2] == $parent && current_user_can( $parent_menu[1] ) )
    731                 $submenu[$parent][] = $parent_menu;
    732         }
    733     }
    734 
    735     $submenu[$parent][] = array ( $menu_title, $access_level, $file, $page_title );
    736 
    737     $hookname = get_plugin_page_hookname( $file, $parent);
     795            if ( $parent_menu[2] == $parent_slug && current_user_can( $parent_menu[1] ) )
     796                $submenu[$parent_slug][] = $parent_menu;
     797        }
     798    }
     799
     800    $submenu[$parent_slug][] = array ( $menu_title, $capability, $menu_slug, $page_title );
     801
     802    $hookname = get_plugin_page_hookname( $menu_slug, $parent_slug);
    738803    if (!empty ( $function ) && !empty ( $hookname ))
    739804        add_action( $hookname, $function );
     
    741806    $_registered_pages[$hookname] = true;
    742807    // backwards-compatibility for plugins using add_management page.  See wp-admin/admin.php for redirect from edit.php to tools.php
    743     if ( 'tools.php' == $parent )
    744         $_registered_pages[get_plugin_page_hookname( $file, 'edit.php')] = true;
     808    if ( 'tools.php' == $parent_slug )
     809        $_registered_pages[get_plugin_page_hookname( $menu_slug, 'edit.php')] = true;
    745810
    746811    return $hookname;
     
    749814/**
    750815 * Add sub menu page to the tools main menu.
    751  *
    752  * @param string $page_title
    753  * @param unknown_type $menu_title
    754  * @param unknown_type $access_level
    755  * @param unknown_type $file
    756  * @param unknown_type $function
    757  * @return unknown
    758  */
    759 function add_management_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    760     return add_submenu_page( 'tools.php', $page_title, $menu_title, $access_level, $file, $function );
    761 }
    762 
    763 function add_options_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    764     return add_submenu_page( 'options-general.php', $page_title, $menu_title, $access_level, $file, $function );
    765 }
    766 
    767 function add_theme_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    768     return add_submenu_page( 'themes.php', $page_title, $menu_title, $access_level, $file, $function );
    769 }
    770 
    771 function add_users_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
     816*
     817 * This function takes a capability which will be used to determine whether
     818 * or not a page is included in the menu.
     819 *
     820 * The function which is hooked in to handle the output of the page must check
     821 * that the user has the required capability as well.
     822 *
     823 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     824 * @param string $menu_title The text to be used for the menu
     825 * @param string $capability The capability required for this menu to be displayed to the user.
     826 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     827 * @param callback $function The function to be called to output the content for this page.
     828 */
     829function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     830    return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $function );
     831}
     832
     833/**
     834 * Add sub menu page to the options main menu.
     835*
     836 * This function takes a capability which will be used to determine whether
     837 * or not a page is included in the menu.
     838 *
     839 * The function which is hooked in to handle the output of the page must check
     840 * that the user has the required capability as well.
     841 *
     842 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     843 * @param string $menu_title The text to be used for the menu
     844 * @param string $capability The capability required for this menu to be displayed to the user.
     845 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     846 * @param callback $function The function to be called to output the content for this page.
     847 */
     848function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     849    return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $function );
     850}
     851
     852/**
     853 * Add sub menu page to the themes main menu.
     854*
     855 * This function takes a capability which will be used to determine whether
     856 * or not a page is included in the menu.
     857 *
     858 * The function which is hooked in to handle the output of the page must check
     859 * that the user has the required capability as well.
     860 *
     861 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     862 * @param string $menu_title The text to be used for the menu
     863 * @param string $capability The capability required for this menu to be displayed to the user.
     864 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     865 * @param callback $function The function to be called to output the content for this page.
     866 */
     867function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     868    return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $function );
     869}
     870
     871/**
     872 * Add sub menu page to the Users/Profile main menu.
     873*
     874 * This function takes a capability which will be used to determine whether
     875 * or not a page is included in the menu.
     876 *
     877 * The function which is hooked in to handle the output of the page must check
     878 * that the user has the required capability as well.
     879 *
     880 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     881 * @param string $menu_title The text to be used for the menu
     882 * @param string $capability The capability required for this menu to be displayed to the user.
     883 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     884 * @param callback $function The function to be called to output the content for this page.
     885 */
     886function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
    772887    if ( current_user_can('edit_users') )
    773888        $parent = 'users.php';
    774889    else
    775890        $parent = 'profile.php';
    776     return add_submenu_page( $parent, $page_title, $menu_title, $access_level, $file, $function );
    777 }
    778 
    779 function add_dashboard_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    780     return add_submenu_page( 'index.php', $page_title, $menu_title, $access_level, $file, $function );
    781 }
    782 
    783 function add_posts_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    784     return add_submenu_page( 'edit.php', $page_title, $menu_title, $access_level, $file, $function );
    785 }
    786 
    787 function add_media_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    788     return add_submenu_page( 'upload.php', $page_title, $menu_title, $access_level, $file, $function );
    789 }
    790 
    791 function add_links_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    792     return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $access_level, $file, $function );
    793 }
    794 
    795 function add_pages_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    796     return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $access_level, $file, $function );
    797 }
    798 
    799 function add_comments_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    800     return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $access_level, $file, $function );
     891    return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $function );
     892}
     893/**
     894 * Add sub menu page to the Dashboard main menu.
     895*
     896 * This function takes a capability which will be used to determine whether
     897 * or not a page is included in the menu.
     898 *
     899 * The function which is hooked in to handle the output of the page must check
     900 * that the user has the required capability as well.
     901 *
     902 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     903 * @param string $menu_title The text to be used for the menu
     904 * @param string $capability The capability required for this menu to be displayed to the user.
     905 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     906 * @param callback $function The function to be called to output the content for this page.
     907 */
     908function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     909    return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $function );
     910}
     911
     912/**
     913 * Add sub menu page to the posts main menu.
     914*
     915 * This function takes a capability which will be used to determine whether
     916 * or not a page is included in the menu.
     917 *
     918 * The function which is hooked in to handle the output of the page must check
     919 * that the user has the required capability as well.
     920 *
     921 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     922 * @param string $menu_title The text to be used for the menu
     923 * @param string $capability The capability required for this menu to be displayed to the user.
     924 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     925 * @param callback $function The function to be called to output the content for this page.
     926 */
     927function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     928    return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $function );
     929}
     930
     931/**
     932 * Add sub menu page to the media main menu.
     933*
     934 * This function takes a capability which will be used to determine whether
     935 * or not a page is included in the menu.
     936 *
     937 * The function which is hooked in to handle the output of the page must check
     938 * that the user has the required capability as well.
     939 *
     940 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     941 * @param string $menu_title The text to be used for the menu
     942 * @param string $capability The capability required for this menu to be displayed to the user.
     943 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     944 * @param callback $function The function to be called to output the content for this page.
     945 */
     946function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     947    return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $function );
     948}
     949
     950/**
     951 * Add sub menu page to the links main menu.
     952*
     953 * This function takes a capability which will be used to determine whether
     954 * or not a page is included in the menu.
     955 *
     956 * The function which is hooked in to handle the output of the page must check
     957 * that the user has the required capability as well.
     958 *
     959 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     960 * @param string $menu_title The text to be used for the menu
     961 * @param string $capability The capability required for this menu to be displayed to the user.
     962 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     963 * @param callback $function The function to be called to output the content for this page.
     964 */
     965function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     966    return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $function );
     967}
     968
     969/**
     970 * Add sub menu page to the pages main menu.
     971*
     972 * This function takes a capability which will be used to determine whether
     973 * or not a page is included in the menu.
     974 *
     975 * The function which is hooked in to handle the output of the page must check
     976 * that the user has the required capability as well.
     977 *
     978 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     979 * @param string $menu_title The text to be used for the menu
     980 * @param string $capability The capability required for this menu to be displayed to the user.
     981 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     982 * @param callback $function The function to be called to output the content for this page.
     983 */
     984function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     985    return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $function );
     986}
     987
     988/**
     989 * Add sub menu page to the comments main menu.
     990*
     991 * This function takes a capability which will be used to determine whether
     992 * or not a page is included in the menu.
     993 *
     994 * The function which is hooked in to handle the output of the page must check
     995 * that the user has the required capability as well.
     996 *
     997 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected
     998 * @param string $menu_title The text to be used for the menu
     999 * @param string $capability The capability required for this menu to be displayed to the user.
     1000 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu)
     1001 * @param callback $function The function to be called to output the content for this page.
     1002 */
     1003function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '' ) {
     1004    return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function );
    8011005}
    8021006
Note: See TracChangeset for help on using the changeset viewer.