Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
10/23/2013 12:14:44 AM (11 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-theme-compatibility.php

    r7432 r7457  
    22
    33/**
    4  * BuddyPress Core Theme Compatibility
     4 * BuddyPress Core Theme Compatibility.
    55 *
    66 * @package BuddyPress
    … …  
    2626
    2727/**
    28  * Theme Compatibility base class
     28 * Theme Compatibility base class.
    2929 *
    3030 * This is only intended to be extended, and is included here as a basic guide
    31  * for future Theme Packs to use. @link BP_Legacy is a good example of
     31 * for future Theme Packs to use. {@link BP_Legacy} is a good example of
    3232 * extending this class.
    3333 *
    34  * @since BuddyPress (1.7)
    35  * @todo We should probably do something similar to BP_Component::start()
     34 * @since BuddyPress (1.7.0)
     35 *
     36 * @todo We should probably do something similar to BP_Component::start().
     37 * @todo If this is only intended to be extended, it should be abstract.
     38 *
     39 * @param array $properties {
     40 *     An array of properties describing the theme compat package.
     41 *     @type string $id ID of the package. Must be unique.
     42 *     @type string $name Name of the theme. This should match the name given
     43 *           in style.css.
     44 *     @type string $version Theme version. Used for busting script and style
     45 *           browser caches.
     46 *     @type string $dir Filesystem path of the theme.
     47 *     @type string $url Base URL of the theme.
     48 * }
    3649 */
    3750class BP_Theme_Compat {
    3851
    3952    /**
    40      * Should be like:
    41      *
    42      * array(
    43      *     'id'      => ID of the theme (should be unique)
    44      *     'name'    => Name of the theme (should match style.css)
    45      *     'version' => Theme version for cache busting scripts and styling
    46      *     'dir'     => Path to theme
    47      *     'url'     => URL to theme
    48      * );
     53     * Template package properties, as passed to the constructor.
     54     *
    4955     * @var array
    5056     */
    … …  
    5460     * Pass the $properties to the object on creation.
    5561     *
    56      * @since BuddyPress (1.7)
    57      * @param array $properties
     62     * @since BuddyPress (1.7.0)
    5863     */
    5964        public function __construct( Array $properties = array() ) {
    … …  
    6166    }
    6267
    63 
    64     /**
    65      * Set up the BuddyPress-specific theme compat methods
     68    /**
     69     * Set up the BuddyPress-specific theme compat methods.
    6670     *
    6771     * Themes shoud use this method in their constructor.
    6872     *
    69      * @since BuddyPress (1.7)
     73     * @since BuddyPress (1.7.0)
    7074     */
    7175    protected function start() {
    … …  
    8185
    8286    /**
    83      * Meant to be extended in your class.
    84      *
    85      * @since BuddyPress (1.7)
     87     * Set up global data for your template package.
     88     *
     89     * Meant to be overridden in your class. See
     90     * {@link BP_Legacy::setup_globals()} for an example.
     91     *
     92     * @since BuddyPress (1.7.0)
    8693     */
    8794    protected function setup_globals() {}
    8895
    8996    /**
    90      * Meant to be extended in your class.
    91      *
    92      * @since BuddyPress (1.7)
     97     * Set up theme hooks for your template package.
     98     *
     99     * Meant to be overridden in your class. See
     100     * {@link BP_Legacy::setup_actions()} for an example.
     101     *
     102     * @since BuddyPress (1.7.0)
    93103     */
    94104    protected function setup_actions() {}
    … …  
    97107     * Set a theme's property.
    98108     *
    99      * @since BuddyPress (1.7)
    100      * @param string $property
    101      * @param mixed $value
    102      * @return mixed
     109     * @since BuddyPress (1.7.0)
     110     *
     111     * @param string $property Property name.
     112     * @param mixed $value Property value.
     113     * @return bool True on success, false on failure.
    103114     */
    104115    public function __set( $property, $value ) {
    … …  
    109120     * Get a theme's property.
    110121     *
    111      * @since BuddyPress (1.7)
    112      * @param string $property
    113      * @param mixed $value
    114      * @return mixed
     122     * @since BuddyPress (1.7.0)
     123     *
     124     * @param string $property Property name.
     125     * @return mixed The value of the property if it exists, otherwise an
     126     *         empty string.
    115127     */
    116128    public function __get( $property ) {
    … …  
    122134
    123135/**
    124  * Setup the default theme compat theme
    125  *
    126  * @since BuddyPress (1.7)
    127  * @param BP_Theme_Compat $theme
     136 * Set up the default theme compat theme.
     137 *
     138 * @since BuddyPress (1.7.0)
     139 *
     140 * @param string $theme Optional. The unique ID identifier of a theme package.
    128141 */
    129142function bp_setup_theme_compat( $theme = '' ) {
    … …  
    140153
    141154/**
    142  * Gets the name of the BuddyPress compatable theme used, in the event the
    143  * currently active WordPress theme does not explicitly support BuddyPress.
     155 * Get the ID of the theme package being used.
     156 *
    144157 * This can be filtered or set manually. Tricky theme authors can override the
    145158 * default and include their own BuddyPress compatability layers for their themes.
    146159 *
    147  * @since BuddyPress (1.7)
     160 * @since BuddyPress (1.7.0)
     161 *
    148162 * @uses apply_filters()
    149  * @return string
     163 *
     164 * @return string ID of the theme package in use.
    150165 */
    151166function bp_get_theme_compat_id() {
    … …  
    154169
    155170/**
    156  * Gets the name of the BuddyPress compatable theme used, in the event the
    157  * currently active WordPress theme does not explicitly support BuddyPress.
     171 * Get the name of the theme package being used.
     172 *
    158173 * This can be filtered or set manually. Tricky theme authors can override the
    159174 * default and include their own BuddyPress compatability layers for their themes.
    160175 *
    161  * @since BuddyPress (1.7)
     176 * @since BuddyPress (1.7.0)
     177 *
    162178 * @uses apply_filters()
    163  * @return string
     179 *
     180 * @return string Name of the theme package currently in use.
    164181 */
    165182function bp_get_theme_compat_name() {
    … …  
    168185
    169186/**
    170  * Gets the version of the BuddyPress compatable theme used, in the event the
    171  * currently active WordPress theme does not explicitly support BuddyPress.
     187 * Get the version of the theme package being used.
     188 *
    172189 * This can be filtered or set manually. Tricky theme authors can override the
    173190 * default and include their own BuddyPress compatability layers for their themes.
    174191 *
    175  * @since BuddyPress (1.7)
     192 * @since BuddyPress (1.7.0)
     193 *
    176194 * @uses apply_filters()
    177  * @return string
     195 *
     196 * @return string The version string of the theme package currently in use.
    178197 */
    179198function bp_get_theme_compat_version() {
    … …  
    182201
    183202/**
    184  * Gets the BuddyPress compatable theme used in the event the currently active
    185  * WordPress theme does not explicitly support BuddyPress. This can be filtered,
     203 * Get the absolute path of the theme package being used.
     204 *
    186205 * or set manually. Tricky theme authors can override the default and include
    187206 * their own BuddyPress compatability layers for their themes.
    188207 *
    189  * @since BuddyPress (1.7)
     208 * @since BuddyPress (1.7.0)
     209 *
    190210 * @uses apply_filters()
    191  * @return string
     211 *
     212 * @return string The absolute path of the theme package currently in use.
    192213 */
    193214function bp_get_theme_compat_dir() {
    … …  
    196217
    197218/**
    198  * Gets the BuddyPress compatable theme used in the event the currently active
    199  * WordPress theme does not explicitly support BuddyPress. This can be filtered,
    200  * or set manually. Tricky theme authors can override the default and include
    201  * their own BuddyPress compatability layers for their themes.
    202  *
    203  * @since BuddyPress (1.7)
     219 * Get the URL of the theme package being used.
     220 *
     221 * This can be filtered, or set manually. Tricky theme authors can override
     222 * the default and include their own BuddyPress compatability layers for their
     223 * themes.
     224 *
     225 * @since BuddyPress (1.7.0)
     226 *
    204227 * @uses apply_filters()
    205  * @return string
     228 *
     229 * @return string URL of the theme package currently in use.
    206230 */
    207231function bp_get_theme_compat_url() {
    … …  
    213237 *
    214238 * If the current theme's need for theme compat hasn't yet been detected, we
    215  * do so using bp_detect_theme_compat_with_current_theme()
     239 * do so using bp_detect_theme_compat_with_current_theme().
    216240 *
    217241 * @since BuddyPress (1.9.0)
    … …  
    219243 * @uses bp_detect_theme_compat_with_current_theme()
    220244 *
    221  * @return bool True if the current theme needs theme compatibility
     245 * @return bool True if the current theme needs theme compatibility.
    222246 */
    223247function bp_use_theme_compat_with_current_theme() {
    … …  
    277301
    278302/**
    279  * Gets true/false if the current, loaded page uses theme compatibility
    280  *
    281  * @since BuddyPress (1.7)
    282  * @return bool
     303 * Is the current page using theme compatibility?
     304 *
     305 * @since BuddyPress (1.7.0)
     306 *
     307 * @return bool True if the current page uses theme compatibility.
    283308 */
    284309function bp_is_theme_compat_active() {
    … …  
    292317
    293318/**
    294  * Sets true/false if page is currently inside theme compatibility
    295  *
    296  * @since BuddyPress (1.7)
    297  * @param bool $set
    298  * @return bool
     319 * Set the flag that tells whether the current page is using theme compatibility.
     320 *
     321 * @since BuddyPress (1.7.0)
     322 *
     323 * @param bool $set True to set the flag to true, false to set it to false.
     324 * @return bool Returns the value of $set.
    299325 */
    300326function bp_set_theme_compat_active( $set = true ) {
    … …  
    305331
    306332/**
    307  * Set the theme compat templates global
     333 * Set the theme compat templates global.
    308334 *
    309335 * Stash possible template files for the current query. Useful if plugins want
    310336 * to override them, or see what files are being scanned for inclusion.
    311337 *
    312  * @since BuddyPress (1.7)
     338 * @since BuddyPress (1.7.0)
     339 *
     340 * @param array $templates The template stack.
     341 * @return array The template stack (value of $templates).
    313342 */
    314343function bp_set_theme_compat_templates( $templates = array() ) {
    … …  
    319348
    320349/**
    321  * Set the theme compat template global
     350 * Set the theme compat template global.
    322351 *
    323352 * Stash the template file for the current query. Useful if plugins want
    324353 * to override it, or see what file is being included.
    325354 *
    326  * @since BuddyPress (1.7)
     355 * @since BuddyPress (1.7.0)
     356 *
     357 * @param string $template The template currently in use.
     358 * @return string The template currently in use (value of $template).
    327359 */
    328360function bp_set_theme_compat_template( $template = '' ) {
    … …  
    333365
    334366/**
    335  * Set the theme compat original_template global
     367 * Set the theme compat original_template global.
    336368 *
    337369 * Stash the original template file for the current query. Useful for checking
    338370 * if BuddyPress was able to find a more appropriate template.
    339371 *
    340  * @since BuddyPress (1.7)
     372 * @since BuddyPress (1.7.0)
     373 *
     374 * @param string $template The template originally selected by WP.
     375 * @return string The template originally selected by WP (value of $template).
    341376 */
    342377function bp_set_theme_compat_original_template( $template = '' ) {
    … …  
    347382
    348383/**
    349  * Set the theme compat original_template global
    350  *
    351  * Stash the original template file for the current query. Useful for checking
    352  * if BuddyPress was able to find a more appropriate template.
    353  *
    354  * @since BuddyPress (1.7)
     384 * Check whether a given template is the one that WP originally selected to display current page.
     385 *
     386 * @since BuddyPress (1.7.0)
     387 *
     388 * @param string $template The template name to check.
     389 * @return bool True if the value of $template is the same as the
     390 *         "original_template" originally selected by WP. Otherwise false.
    355391 */
    356392function bp_is_theme_compat_original_template( $template = '' ) {
    … …  
    364400
    365401/**
    366  * Register a new BuddyPress theme package to the active theme packages array
    367  *
    368  * The $theme parameter is an array, which takes the following values:
    369  *
    370  *  'id'      - ID for your theme package; should be alphanumeric only
    371  *  'name'    - Name of your theme package
    372  *  'version' - Version of your theme package
    373  *  'dir'     - Directory where your theme package resides
    374  *  'url'     - URL where your theme package resides
     402 * Register a new BuddyPress theme package in the active theme packages array.
    375403 *
    376404 * For an example of how this function is used, see:
    … …  
    379407 * @since BuddyPress (1.7)
    380408 *
    381  * @param array $theme The theme package arguments. See phpDoc for more details.
     409 * @see BP_Theme_Compat for a description of the $theme parameter arguments.
     410 *
     411 * @param array $theme See {@link BP_Theme_Compat}.
    382412 * @param bool $override If true, overrides whatever package is currently set.
     413 *        Default: true.
    383414 */
    384415function bp_register_theme_package( $theme = array(), $override = true ) {
    … …  
    405436
    406437/**
    407  * This fun little function fills up some WordPress globals with dummy data to
    408  * stop your average page template from complaining about it missing.
    409  *
    410  * @since BuddyPress (1.7)
    411  * @global WP_Query $wp_query
    412  * @global object $post
    413  * @param array $args
     438 * Populate various WordPress globals with dummy data to prevent errors.
     439 *
     440 * This dummy data is necessary because theme compatibility essentially fakes
     441 * WordPress into thinking that there is content where, in fact, there is none
     442 * (at least, no WordPress post content). By providing dummy data, we ensure
     443 * that template functions - things like is_page() - don't throw errors.
     444 *
     445 * @since BuddyPress (1.7.0)
     446 *
     447 * @global WP_Query $wp_query WordPress database access object.
     448 * @global object $post Current post object.
     449 *
     450 * @param array $args Array of optional arguments. Arguments parallel the
     451 *        properties of {@link WP_Post}; see that class for more details.
    414452 */
    415453function bp_theme_compat_reset_post( $args = array() ) {
    … …  
    522560
    523561/**
    524  * Reset main query vars and filter 'the_content' to output a BuddyPress
    525  * template part as needed.
    526  *
    527  * @since BuddyPress (1.7)
    528  *
    529  * @param string $template
    530  * @uses bp_is_single_user() To check if page is single user
    531  * @uses bp_get_single_user_template() To get user template
    532  * @uses bp_is_single_user_edit() To check if page is single user edit
    533  * @uses bp_get_single_user_edit_template() To get user edit template
    534  * @uses bp_is_single_view() To check if page is single view
    535  * @uses bp_get_single_view_template() To get view template
    536  * @uses bp_is_forum_edit() To check if page is forum edit
    537  * @uses bp_get_forum_edit_template() To get forum edit template
    538  * @uses bp_is_topic_merge() To check if page is topic merge
    539  * @uses bp_get_topic_merge_template() To get topic merge template
    540  * @uses bp_is_topic_split() To check if page is topic split
    541  * @uses bp_get_topic_split_template() To get topic split template
    542  * @uses bp_is_topic_edit() To check if page is topic edit
    543  * @uses bp_get_topic_edit_template() To get topic edit template
    544  * @uses bp_is_reply_edit() To check if page is reply edit
    545  * @uses bp_get_reply_edit_template() To get reply edit template
    546  * @uses bp_set_theme_compat_template() To set the global theme compat template
     562 * Reset main query vars and filter 'the_content' to output a BuddyPress template part as needed.
     563 *
     564 * @since BuddyPress (1.7.0)
     565 *
     566 * @uses bp_is_single_user() To check if page is single user.
     567 * @uses bp_get_single_user_template() To get user template.
     568 * @uses bp_is_single_user_edit() To check if page is single user edit.
     569 * @uses bp_get_single_user_edit_template() To get user edit template.
     570 * @uses bp_is_single_view() To check if page is single view.
     571 * @uses bp_get_single_view_template() To get view template.
     572 * @uses bp_is_forum_edit() To check if page is forum edit.
     573 * @uses bp_get_forum_edit_template() To get forum edit template.
     574 * @uses bp_is_topic_merge() To check if page is topic merge.
     575 * @uses bp_get_topic_merge_template() To get topic merge template.
     576 * @uses bp_is_topic_split() To check if page is topic split.
     577 * @uses bp_get_topic_split_template() To get topic split template.
     578 * @uses bp_is_topic_edit() To check if page is topic edit.
     579 * @uses bp_get_topic_edit_template() To get topic edit template.
     580 * @uses bp_is_reply_edit() To check if page is reply edit.
     581 * @uses bp_get_reply_edit_template() To get reply edit template.
     582 * @uses bp_set_theme_compat_template() To set the global theme compat template.
     583 *
     584 * @param string $template Template name.
     585 * @return string $template Template name.
    547586 */
    548587function bp_template_include_theme_compat( $template = '' ) {
    … …  
    596635
    597636/**
     637 * Conditionally replace 'the_content'.
     638 *
    598639 * Replaces the_content() if the post_type being displayed is one that would
    599640 * normally be handled by BuddyPress, but proper single page templates do not
    600641 * exist in the currently active theme.
    601642 *
    602  * @since BuddyPress (1.7)
    603  * @param string $content
    604  * @return string
     643 * @since BuddyPress (1.7.0)
     644 *
     645 * @param string $content Original post content.
     646 * @return string $content Post content, potentially modified.
    605647 */
    606648function bp_replace_the_content( $content = '' ) {
    … …  
    635677
    636678/**
    637  * Are we replacing the_content
    638  *
    639  * @since BuddyPress (1.8)
    640  * @return bool
     679 * Are we currently replacing the_content?
     680 *
     681 * @since BuddyPress (1.8.0)
     682 *
     683 * @return bool True if the_content is currently in the process of being
     684 *         filtered and replaced.
    641685 */
    642686function bp_do_theme_compat() {
    … …  
    647691
    648692/**
    649  * Removes all filters from a WordPress filter, and stashes them in the $bp
    650  * global in the event they need to be restored later.
    651  *
    652  * @since BuddyPress (1.7)
     693 * Remove all filters from a WordPress filter hook.
     694 *
     695 * Removed filters are stashed in the $bp global, in case they need to be
     696 * restored later.
     697 *
     698 * @since BuddyPress (1.7.0)
     699 *
    653700 * @global WP_filter $wp_filter
    654701 * @global array $merged_filters
    655  * @param string $tag
    656  * @param int $priority
    657  * @return bool
     702 *
     703 * @param string $tag The filter tag to remove filters from.
     704 * @param int $priority Optional. If present, only those callbacks attached
     705 *        at a given priority will be removed. Otherwise, all callbacks
     706 *        attached to the tag will be removed, regardless of priority.
     707 * @return bool True on success.
    658708 */
    659709function bp_remove_all_filters( $tag, $priority = false ) {
    … …  
    699749
    700750/**
    701  * Restores filters from the $bp global that were removed using
    702  * bp_remove_all_filters()
    703  *
    704  * @since BuddyPress (1.7)
     751 * Restore filters that were removed using bp_remove_all_filters().
     752 *
     753 * @since BuddyPress (1.7.0)
     754 *
    705755 * @global WP_filter $wp_filter
    706756 * @global array $merged_filters
    707  * @param string $tag
    708  * @param int $priority
    709  * @return bool
     757 *
     758 * @param string $tag The tag to which filters should be restored.
     759 * @param int $priority Optional. If present, only those filters that were
     760 *        originally attached to the tag with $priority will be restored.
     761 *        Otherwise, all available filters will be restored, regardless of
     762 *        priority.
     763 * @return bool True on success.
    710764 */
    711765function bp_restore_all_filters( $tag, $priority = false ) {
    … …  
    751805
    752806/**
    753  * Force comments_status to 'closed' for BuddyPress post types
    754  *
    755  * @since BuddyPress (1.7)
    756  * @param bool $open True if open, false if closed
    757  * @param int $post_id ID of the post to check
    758  * @return bool True if open, false if closed
     807 * Force comments_status to 'closed' for BuddyPress post types.
     808 *
     809 * @since BuddyPress (1.7.0)
     810 *
     811 * @param bool $open True if open, false if closed.
     812 * @param int $post_id ID of the post to check.
     813 * @return bool True if open, false if closed.
    759814 */
    760815function bp_comments_open( $open, $post_id = 0 ) {
Note: See TracChangeset for help on using the changeset viewer.