Skip to:
Content

BuddyPress.org

Changeset 7445


Ignore:
Timestamp:
10/19/2013 01:21:35 PM (10 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-core. See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/bp-core/bp-core-component.php

    r7410 r7445  
    11<?php
    22/**
    3  * Component classes
     3 * Component classes.
    44 *
    55 * @package BuddyPress
     
    1212if ( !class_exists( 'BP_Component' ) ) :
    1313/**
    14  * BuddyPress Component Class
     14 * BuddyPress Component Class.
    1515 *
    1616 * The BuddyPress component class is responsible for simplifying the creation
     
    2222 * @subpackage Component
    2323 *
    24  * @since BuddyPress (1.5)
     24 * @since BuddyPress (1.5.0)
    2525 */
    2626class BP_Component {
     
    2929
    3030    /**
    31      * @var string Unique name (for internal identification)
     31     * Translatable name for the component.
     32     *
    3233     * @internal
     34     * @var string $name
    3335     */
    3436    public $name = '';
    3537
    3638    /**
    37      * @var Unique ID (normally for custom post type)
     39     * Unique ID for the component.
     40     *
     41     * @var string $id
    3842     */
    3943    public $id = '';
    4044
    4145    /**
    42      * @var string Unique slug (used in query string and permalinks)
     46     * Unique slug for the component, for use in query strings and URLs.
     47     *
     48     * @var string $slug
    4349     */
    4450    public $slug = '';
    4551
    4652    /**
    47      * @var bool Does this component need a top-level directory?
     53     * Does the component need a top-level directory?
     54     *
     55     * @var bool $has_directory
    4856     */
    4957    public $has_directory = false;
    5058
    5159    /**
    52      * @var string The path to the component's files
     60     * The path to the component's files.
     61     *
     62     * @var string $path
    5363     */
    5464    public $path = '';
    5565
    5666    /**
    57      * @var WP_Query The loop for this component
     67     * The WP_Query loop for this component.
     68     *
     69     * @var WP_Query $query
    5870     */
    5971    public $query = false;
    6072
    6173    /**
    62      * @var string The current ID of the queried object
     74     * The current ID of the queried object.
     75     *
     76     * @var string $current_id
    6377     */
    6478    public $current_id = '';
    6579
    6680    /**
    67      * @var string Function to call for notifications
     81     * Callback for formatting notifications.
     82     *
     83     * @var callable $notification_callback
    6884     */
    6985    public $notification_callback = '';
    7086
    7187    /**
    72      * @var array WordPress Toolbar links
     88     * WordPress Toolbar links.
     89     *
     90     * @var array $admin_menu
    7391     */
    7492    public $admin_menu = '';
    7593
    7694    /**
    77      * Search input box placeholder string for the component
    78      *
    79      * @since BuddyPress (1.5)
    80      * @var string
     95     * Placeholder text for component directory search box.
     96     *
     97     * @since BuddyPress (1.5.0)
     98     * @var string $search_string
    8199     */
    82100    public $search_string = '';
    83101
    84102    /**
    85      * Component's root slug
    86      *
    87      * @since BuddyPress (1.5)
    88      * @var string
     103     * Root slug for the component.
     104     *
     105     * @since BuddyPress (1.5.0)
     106     * @var string $root_slug
    89107     */
    90108    public $root_slug = '';
     
    93111
    94112    /**
    95      * Component loader
    96      *
    97      * @since BuddyPress (1.5)
    98      *
    99      * @param string $id Unique ID (for internal identification). Letters, numbers, and underscores only
    100      * @param string $name Unique name. This should be a translatable name, eg __( 'Groups', 'buddypress' )
    101      * @param string $path The file path for the component's files. Used by BP_Component::includes()
    102      *
    103      * @uses bp_Component::setup_actions() Setup the hooks and actions
     113     * Component loader.
     114     *
     115     * @since BuddyPress (1.5.0)
     116     *
     117     * @uses bp_Component::setup_actions() Set up the hooks and actions.
     118     *
     119     * @param string $id Unique ID (for internal identification). Letters,
     120     *        numbers, and underscores only.
     121     * @param string $name Unique name. This should be a translatable name,
     122     *        eg __( 'Groups', 'buddypress' ).
     123     * @param string $path The file path for the component's files. Used by
     124     *        {@link BP_Component::includes()}.
    104125     */
    105126    public function start( $id = '', $name = '', $path = '' ) {
     
    129150     *     All values are optional.
    130151     *     @type string $slug The component slug. Used to construct certain
    131      *                        URLs, such as 'friends' in
    132      *                        http://example.com/members/joe/friends/
     152     *           URLs, such as 'friends' in http://example.com/members/joe/friends/
     153     *           Default: the value of $this->id.
    133154     *     @type string $root_slug The component root slug. Note that this
    134      *                             value is generally unused if the component
    135      *                             has a root directory (the slug will be
    136      *                             overridden by the post_name of the
    137      *                             directory page).
     155     *           value is generally unused if the component has a root
     156     *           directory (the slug will be overridden by the post_name of
     157     *           the directory page).
    138158     *     @type bool $has_directory Set to true if the component requires
    139      *                               an associated WordPress page.
    140      *     @type string $notification_callback The callable function that
    141      *                                         formats the component's
    142      *                                         notifications.
     159     *           an associated WordPress page.
     160     *     @type callable $notification_callback Optional. The callable
     161     *           function that formats the component's notifications.
    143162     *     @type string $search_term Optional. The placeholder text in the
    144      *                               component directory search box. Eg,
    145      *                               'Search Groups...'.
     163     *           component directory search box. Eg, 'Search Groups...'.
    146164     *     @type array $global_tables Optional. An array of database table
    147      *                                names.
     165     *           names.
    148166     * }
    149167     */
     
    198216
    199217    /**
    200      * Include required files
    201      *
    202      * Please note that, by default, this method is fired on the bp_include hook, with priority
    203      * 8. This is necessary so that core components are loaded in time to be available to
    204      * third-party plugins. However, this load order means that third-party plugins whose main
    205      * files are loaded at bp_include with priority 10 (as recommended), will not be loaded in
    206      * time for their includes() method to fire automatically.
    207      *
    208      * For this reason, it is recommended that your plugin has its own method or function for
    209      * requiring necessary files. If you must use this method, you will have to call it manually
    210      * in your constructor class, ie
     218     * Include required files.
     219     *
     220     * Please note that, by default, this method is fired on the bp_include
     221     * hook, with priority 8. This is necessary so that core components are
     222     * loaded in time to be available to third-party plugins. However, this
     223     * load order means that third-party plugins whose main files are
     224     * loaded at bp_include with priority 10 (as recommended), will not be
     225     * loaded in time for their includes() method to fire automatically.
     226     *
     227     * For this reason, it is recommended that your plugin has its own
     228     * method or function for requiring necessary files. If you must use
     229     * this method, you will have to call it manually in your constructor
     230     * class, ie
    211231     *   $this->includes();
    212232     *
    213      * Note that when you pass an array value like 'actions' to includes, it looks for the
    214      * following three files (assuming your component is called 'my_component'):
     233     * Note that when you pass an array value like 'actions' to includes,
     234     * it looks for the following three files (assuming your component is
     235     * called 'my_component'):
    215236     *   - ./actions
    216237     *   - ./bp-my_component/actions
    217238     *   - ./bp-my_component/bp-my_component-actions.php
    218239     *
    219      * @since BuddyPress (1.5)
    220      *
    221      * @uses do_action() Calls 'bp_{@link bp_Component::name}includes'
     240     * @since BuddyPress (1.5.0)
     241     *
     242     * @uses do_action() Calls 'bp_{@link bp_Component::name}includes'.
    222243     *
    223244     * @param array $includes An array of file names, or file name chunks,
    224      *                        to be parsed and then included.
     245     *        to be parsed and then included.
    225246     */
    226247    public function includes( $includes = array() ) {
     
    261282
    262283    /**
    263      * Setup the actions
    264      *
    265      * @since BuddyPress (1.5)
    266      *
    267      * @uses add_action() To add various actions
    268      * @uses do_action() Calls 'bp_{@link BP_Component::name}setup_actions'
     284     * Set up the actions.
     285     *
     286     * @since BuddyPress (1.5.0)
     287     *
     288     * @uses add_action() To add various actions.
     289     * @uses do_action() Calls 'bp_{@link BP_Component::name}setup_actions'.
    269290     */
    270291    public function setup_actions() {
     
    323344     *
    324345     * @param array $main_nav Optional. Passed directly to
    325      *                        bp_core_new_nav_item(). See that function for
    326      *                        a description.
     346     *        bp_core_new_nav_item(). See that function for a description.
    327347     * @param array $sub_nav Optional. Multidimensional array, each item in
    328      *                       which is passed to bp_core_new_subnav_item().
    329      *                       See that function for a description.
     348     *        which is passed to bp_core_new_subnav_item(). See that
     349     *        function for a description.
    330350     */
    331351    public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
     
    355375     *
    356376     * @param array $wp_admin_nav An array of nav item arguments. Each item
    357      *                            in this parameter array is passed to
    358      *                            WP_Admin_Bar::add_menu(). See that method
    359      *                            for a description of the required syntax
    360      *                            for each item.
     377     *        in this parameter array is passed to {@link WP_Admin_Bar::add_menu()}.
     378     *        See that method for a description of the required syntax for
     379     *        each item.
    361380     */
    362381    public function setup_admin_bar( $wp_admin_nav = array() ) {
     
    393412
    394413    /**
    395      * Setup the component title
    396      *
    397      * @since BuddyPress (1.5)
    398      *
    399      * @uses do_action() Calls 'bp_{@link bp_Component::name}setup_title'
     414     * Set up the component title.
     415     *
     416     * @since BuddyPress (1.5.0)
     417     *
     418     * @uses do_action() Calls 'bp_{@link bp_Component::name}setup_title'.
    400419     */
    401420    public function setup_title() {
     
    404423
    405424    /**
    406      * Setup the component post types
    407      *
    408      * @since BuddyPress (1.5)
    409      *
    410      * @uses do_action() Calls 'bp_{@link bp_Component::name}_register_post_types'
     425     * Set up the component post types.
     426     *
     427     * @since BuddyPress (1.5.0)
     428     *
     429     * @uses do_action() Calls 'bp_{@link bp_Component::name}_register_post_types'.
    411430     */
    412431    public function register_post_types() {
     
    415434
    416435    /**
    417      * Register component specific taxonomies
    418      *
    419      * @since BuddyPress (1.5)
    420      *
    421      * @uses do_action() Calls 'bp_{@link bp_Component::name}_register_taxonomies'
     436     * Register component-specific taxonomies.
     437     *
     438     * @since BuddyPress (1.5.0)
     439     *
     440     * @uses do_action() Calls 'bp_{@link bp_Component::name}_register_taxonomies'.
    422441     */
    423442    public function register_taxonomies() {
     
    426445
    427446    /**
    428      * Add any additional rewrite tags
    429      *
    430      * @since BuddyPress (1.5)
    431      *
    432      * @uses do_action() Calls 'bp_{@link bp_Component::name}_add_rewrite_tags'
     447     * Add any additional rewrite tags.
     448     *
     449     * @since BuddyPress (1.5.0)
     450     *
     451     * @uses do_action() Calls 'bp_{@link bp_Component::name}_add_rewrite_tags'.
    433452     */
    434453    public function add_rewrite_tags() {
     
    437456
    438457    /**
    439      * Add any additional rewrite rules
    440      *
    441      * @since BuddyPress (1.9)
    442      *
    443      * @uses do_action() Calls 'bp_{@link bp_Component::name}_add_rewrite_rules'
     458     * Add any additional rewrite rules.
     459     *
     460     * @since BuddyPress (1.9.0)
     461     *
     462     * @uses do_action() Calls 'bp_{@link bp_Component::name}_add_rewrite_rules'.
    444463     */
    445464    public function add_rewrite_rules() {
Note: See TracChangeset for help on using the changeset viewer.