Skip to:
Content

BuddyPress.org

Changeset 9740


Ignore:
Timestamp:
04/11/2015 03:09:57 AM (11 years ago)
Author:
tw2113
Message:

Adds hooks documentation for bp-core-avatars.php.

See #5940.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/bp-core/bp-core-avatars.php

    r9698 r9740  
    8888        define( 'BP_AVATAR_URL', $bp->avatar->url );
    8989
     90    /**
     91     * Fires at the end of the core avatar globals setup.
     92     *
     93     * @since BuddyPress (1.5.0)
     94     */
    9095    do_action( 'bp_core_set_avatar_globals' );
    9196}
    … …  
    227232        }
    228233
     234        /**
     235         * Filters the ID of the item being requested.
     236         *
     237         * @since BuddyPress (1.1.0)
     238         *
     239         * @param string $value  ID of avatar item being requested.
     240         * @param string $value  Avatar type being requested.
     241         * @param array  $params Array of parameters for the request.
     242         */
    229243        $params['item_id'] = apply_filters( 'bp_core_avatar_item_id', $params['item_id'], $params['object'], $params );
    230244
    … …  
    259273        }
    260274
     275        /**
     276         * Filters the avatar directory to use.
     277         *
     278         * @since BuddyPress (1.1.0)
     279         *
     280         * @param string $value  Name of the subdirectory where the requested avatar should be found.
     281         * @param string $value  Avatar type being requested.
     282         * @param array  $params Array of parameters for the request.
     283         */
    261284        $params['avatar_dir'] = apply_filters( 'bp_core_avatar_dir', $params['avatar_dir'], $params['object'], $params );
    262285
    … …  
    286309        }
    287310
     311        /**
     312         * Filters the alt attribute value to be applied to avatar.
     313         *
     314         * @since BuddyPress (1.5.0)
     315         *
     316         * @param string $value  alt to be applied to avatar.
     317         * @param string $value  ID of avatar item being requested.
     318         * @param string $value  Avatar type being requested.
     319         * @param array  $params Array of parameters for the request.
     320         */
    288321        $item_name = apply_filters( 'bp_core_avatar_alt', $item_name, $params['item_id'], $params['object'], $params );
    289322        $params['alt'] = sprintf( $params['alt'], $item_name );
    … …  
    300333    // Filter image title and create html string
    301334    $html_title = '';
     335
     336    /**
     337     * Filters the title attribute value to be applied to avatar.
     338     *
     339     * @since BuddyPress (1.5.0)
     340     *
     341     * @param string $value  Title to be applied to avatar.
     342     * @param string $value  ID of avatar item being requested.
     343     * @param string $value  Avatar type being requested.
     344     * @param array  $params Array of parameters for the request.
     345     */
    302346    $params['title'] = apply_filters( 'bp_core_avatar_title', $params['title'], $params['item_id'], $params['object'], $params );
    303347
    … …  
    308352    // Set CSS ID and create html string
    309353    $html_css_id = '';
     354
     355    /**
     356     * Filters the ID attribute to be applied to avatar.
     357     *
     358     * @since BuddyPress (2.2.0)
     359     *
     360     * @param string $value  ID to be applied to avatar.
     361     * @param string $value  ID of avatar item being requested.
     362     * @param string $value  Avatar type being requested.
     363     * @param array  $params Array of parameters for the request.
     364     */
    310365    $params['css_id'] = apply_filters( 'bp_core_css_id', $params['css_id'], $params['item_id'], $params['object'], $params );
    311366
    … …  
    334389    $html_height = ' height="' . $params['height'] . '"';
    335390
    336     // Create CSS class html string
     391    /**
     392     * Filters the classes to be applied to the avatar.
     393     *
     394     * @since BuddyPress (1.6.0)
     395     *
     396     * @param array|string $value  Class(es) to be applied to the avatar.
     397     * @param string       $value  ID of the avatar item being requested.
     398     * @param string       $value  Avatar type being requested.
     399     * @param array        $params Array of parameters for the request.
     400     */
    337401    $params['class'] = apply_filters( 'bp_core_avatar_class', $params['class'], $params['item_id'], $params['object'], $params );
    338402
    … …  
    361425
    362426    $avatar_loc->dir   = trailingslashit( $params['avatar_dir'] );
     427
     428    /**
     429     * Filters the avatar folder directory URL.
     430     *
     431     * @since BuddyPress (1.1.0)
     432     *
     433     * @param string $value Path to the avatar folder URL.
     434     * @param int    $value ID of the avatar item being requested.
     435     * @param string $value Avatar type being requested.
     436     * @param string $value Subdirectory where the requested avatar should be found.
     437     */
    363438    $avatar_folder_url = apply_filters( 'bp_core_avatar_folder_url', ( $avatar_loc->url  . $avatar_loc->dir . $params['item_id'] ), $params['item_id'], $params['object'], $params['avatar_dir'] );
     439
     440    /**
     441     * Filters the avatar folder directory path.
     442     *
     443     * @since BuddyPress (1.1.0)
     444     *
     445     * @param string $value Path to the avatar folder directory.
     446     * @param int    $value ID of the avatar item being requested.
     447     * @param string $value Avatar type being requested.
     448     * @param string $value Subdirectory where the requested avatar should be found.
     449     */
    364450    $avatar_folder_dir = apply_filters( 'bp_core_avatar_folder_dir', ( $avatar_loc->path . $avatar_loc->dir . $params['item_id'] ), $params['item_id'], $params['object'], $params['avatar_dir'] );
    365451
    … …  
    426512            // Return it wrapped in an <img> element
    427513            if ( true === $params['html'] ) {
     514
     515                /**
     516                 * Filters an avatar URL wrapped in an <img> element.
     517                 *
     518                 * @since BuddyPress (1.1.0)
     519                 *
     520                 * @param string $value             Full <img> element for an avatar.
     521                 * @param array  $params            Array of parameters for the request.
     522                 * @param string $value             ID of the item requested.
     523                 * @param string $value             Subdirectory where the requested avatar should be found.
     524                 * @param string $html_css_id       ID attribute for avatar.
     525                 * @param string $html_width        Width attribute for avatar.
     526                 * @param string $html_height       Height attribtue for avatar.
     527                 * @param string $avatar_folder_url Avatar URL path.
     528                 * @param string $avatar_folder_dir Avatar dir path.
     529                 */
    428530                return apply_filters( 'bp_core_fetch_avatar', '<img src="' . $avatar_url . '"' . $html_class . $html_css_id  . $html_width . $html_height . $html_alt . $html_title . ' />', $params, $params['item_id'], $params['avatar_dir'], $html_css_id, $html_width, $html_height, $avatar_folder_url, $avatar_folder_dir );
    429531
    430532            // ...or only the URL
    431533            } else {
     534
     535                /**
     536                 * Filters a locally uploaded avatar URL.
     537                 *
     538                 * @since BuddyPress (1.2.5)
     539                 *
     540                 * @param string $avatar_url URL for a locally uploaded avatar.
     541                 * @param array  $params     Array of parameters for the request.
     542                 */
    432543                return apply_filters( 'bp_core_fetch_avatar_url', $avatar_url, $params );
    433544            }
    … …  
    435546    }
    436547
    437     // If no avatars could be found, try to display a gravatar
    438 
    439     // Skips gravatar check if $params['no_grav'] is passed
     548    /**
     549     * Filters whether or not to skip Gravatar check.
     550     *
     551     * @since BuddyPress (1.5.0)
     552     *
     553     * @param bool  $value  Whether or not to skip Gravatar.
     554     * @param array $params Array of parameters for the avatar request.
     555     */
    440556    if ( ! apply_filters( 'bp_core_fetch_avatar_no_grav', $params['no_grav'], $params ) ) {
    441557
    … …  
    444560            $default_grav = 'wavatar';
    445561        } elseif ( 'mystery' == $bp->grav_default->{$params['object']} ) {
     562
     563            /**
     564             * Filters the Mysteryman avatar src value.
     565             *
     566             * @since BuddyPress (1.2.0)
     567             *
     568             * @param string $value Avatar value.
     569             * @param string $value Width to display avatar at.
     570             */
    446571            $default_grav = apply_filters( 'bp_core_mysteryman_src', 'mm', $params['width'] );
    447572        } else {
    … …  
    460585        $host = '//www.gravatar.com/avatar/';
    461586
    462         // Filter gravatar vars
     587        /**
     588         * Filters the Gravatar email to use.
     589         *
     590         * @since BuddyPress (1.1.0)
     591         *
     592         * @param string $value Email to use in Gravatar request.
     593         * @param string $value ID of the item being requested.
     594         * @param string $value Object type being requested.
     595         */
    463596        $params['email'] = apply_filters( 'bp_core_gravatar_email', $params['email'], $params['item_id'], $params['object'] );
     597
     598        /**
     599         * Filters the Gravatar URL path.
     600         *
     601         * @since BuddyPress (1.0.2)
     602         *
     603         * @param string $value Gravatar URL path.
     604         */
    464605        $gravatar = apply_filters( 'bp_gravatar_url', $host ) . md5( strtolower( $params['email'] ) ) . '?d=' . $default_grav . '&amp;s=' . $params['width'];
    465606
    … …  
    472613    // No avatar was found, and we've been told not to use a gravatar.
    473614    } else {
     615
     616        /**
     617         * Filters the avatar default when Gravatar is not used.
     618         *
     619         * This is a variable filter dependent on the avatar type being requested.
     620         *
     621         * @since BuddyPress (1.5.0)
     622         *
     623         * @param string $value  Default avatar for non-gravatar requests.
     624         * @param array  $params Array of parameters for the avatar request.
     625         */
    474626        $gravatar = apply_filters( 'bp_core_default_avatar_' . $params['object'], bp_core_avatar_default( 'local' ), $params );
    475627    }
    476628
    477629    if ( true === $params['html'] ) {
     630
     631        /** This filter is documented in bp-core/bp-core-avatars.php */
    478632        return apply_filters( 'bp_core_fetch_avatar', '<img src="' . $gravatar . '"' . $html_css_id . $html_class . $html_width . $html_height . $html_alt . $html_title . ' />', $params, $params['item_id'], $params['avatar_dir'], $html_css_id, $html_width, $html_height, $avatar_folder_url, $avatar_folder_dir );
    479633    } else {
     634
     635        /** This filter is documented in bp-core/bp-core-avatars.php */
    480636        return apply_filters( 'bp_core_fetch_avatar_url', $gravatar, $params );
    481637    }
    … …  
    516672            $item_id = $current_blog->id;
    517673
     674        /** This filter is documented in bp-core/bp-core-avatars.php */
    518675        $item_id = apply_filters( 'bp_core_avatar_item_id', $item_id, $object );
    519676
    … …  
    529686            $avatar_dir = 'blog-avatars';
    530687
     688        /** This filter is documented in bp-core/bp-core-avatars.php */
    531689        $avatar_dir = apply_filters( 'bp_core_avatar_dir', $avatar_dir, $object );
    532690
    … …  
    534692    }
    535693
     694    /** This filter is documented in bp-core/bp-core-avatars.php */
    536695    $avatar_folder_dir = apply_filters( 'bp_core_avatar_folder_dir', bp_core_avatar_upload_path() . '/' . $avatar_dir . '/' . $item_id, $item_id, $object, $avatar_dir );
    537696
    … …  
    549708    @rmdir( $avatar_folder_dir );
    550709
     710    /**
     711     * Fires after deleting an existing avatar.
     712     *
     713     * @since BuddyPress (1.1.0)
     714     *
     715     * @param array $args Array of arguments used for avatar deletion.
     716     */
    551717    do_action( 'bp_core_delete_existing_avatar', $args );
    552718
    … …  
    573739function bp_core_avatar_handle_upload( $file, $upload_dir_filter ) {
    574740
    575     /***
    576      * You may want to hook into this filter if you want to override this function.
    577      * Make sure you return false.
     741    /**
     742     * Filters whether or not to handle uploading.
     743     *
     744     * If you want to override this function, make sure you return false.
     745     *
     746     * @since BuddyPress (1.2.4)
     747     *
     748     * @param bool   $value             Whether or not to crop.
     749     * @param array  $file              Appropriate entry from $_FILES superglobal.
     750     * @parma string $upload_dir_filter A filter to be applied to 'upload_dir'.
    578751     */
    579752    if ( ! apply_filters( 'bp_core_pre_avatar_handle_upload', true, $file, $upload_dir_filter ) ) {
    … …  
    670843    ) );
    671844
    672     /***
    673      * You may want to hook into this filter if you want to override this function.
    674      * Make sure you return false.
     845    /**
     846     * Filters whether or not to handle cropping.
     847     *
     848     * If you want to override this function, make sure you return false.
     849     *
     850     * @since BuddyPress (1.2.4)
     851     *
     852     * @param bool  $value Whether or not to crop.
     853     * @param array $r     Array of parsed arguments for function
    675854     */
    676855    if ( ! apply_filters( 'bp_core_pre_avatar_handle_crop', true, $r ) ) {
    … …  
    8831062 */
    8841063function bp_core_avatar_upload_path() {
     1064
     1065    /**
     1066     * Filters the absolute upload path for the WP installation.
     1067     *
     1068     * @since BuddyPress (1.2.0)
     1069     *
     1070     * @param string $value Absolute upload path for the WP installation.
     1071     */
    8851072    return apply_filters( 'bp_core_avatar_upload_path', bp_core_get_upload_dir() );
    8861073}
    … …  
    8941081 */
    8951082function bp_core_avatar_url() {
     1083
     1084    /**
     1085     * Filters the raw base URL for root site upload location.
     1086     *
     1087     * @since BuddyPress (1.2.0)
     1088     *
     1089     * @param string $value Raw base URL for the root site upload location.
     1090     */
    8961091    return apply_filters( 'bp_core_avatar_url', bp_core_get_upload_dir( 'url' ) );
    8971092}
    … …  
    9141109        $retval = true;
    9151110
     1111    /**
     1112     * Filters whether or not a user has an uploaded avatar.
     1113     *
     1114     * @since BuddyPress (1.6.0)
     1115     *
     1116     * @param bool $retval  Whether or not a user has an uploaded avatar.
     1117     * @param int  $user_id ID of the user being checked.
     1118     */
    9161119    return (bool) apply_filters( 'bp_get_user_has_avatar', $retval, $user_id );
    9171120}
    … …  
    9321135    $dim = isset( $bp->avatar->{$type}->{$h_or_w} ) ? (int) $bp->avatar->{$type}->{$h_or_w} : false;
    9331136
     1137    /**
     1138     * Filters the avatar dimension setting.
     1139     *
     1140     * @since BuddyPress (1.5.0)
     1141     *
     1142     * @param int    $dim    Dimension setting for the type.
     1143     * @param string $type   The type of avatar whose dimensions are requested. Default 'thumb'.
     1144     * @param string $h_or_w The dimension parameter being requested. Default 'height'.
     1145     */
    9341146    return apply_filters( 'bp_core_avatar_dimension', $dim, $type, $h_or_w );
    9351147}
    … …  
    9431155 */
    9441156function bp_core_avatar_thumb_width() {
     1157
     1158    /**
     1159     * Filters the 'thumb' avatar width setting.
     1160     *
     1161     * @since BuddyPress (1.5.0)
     1162     *
     1163     * @param int $value Value for the 'thumb' avatar width setting.
     1164     */
    9451165    return apply_filters( 'bp_core_avatar_thumb_width', bp_core_avatar_dimension( 'thumb', 'width' ) );
    9461166}
    … …  
    9541174 */
    9551175function bp_core_avatar_thumb_height() {
     1176
     1177    /**
     1178     * Filters the 'thumb' avatar height setting.
     1179     *
     1180     * @since BuddyPress (1.5.0)
     1181     *
     1182     * @param int $value Value for the 'thumb' avatar height setting.
     1183     */
    9561184    return apply_filters( 'bp_core_avatar_thumb_height', bp_core_avatar_dimension( 'thumb', 'height' ) );
    9571185}
    … …  
    9651193 */
    9661194function bp_core_avatar_full_width() {
     1195
     1196    /**
     1197     * Filters the 'full' avatar width setting.
     1198     *
     1199     * @since BuddyPress (1.5.0)
     1200     *
     1201     * @param int $value Value for the 'full' avatar width setting.
     1202     */
    9671203    return apply_filters( 'bp_core_avatar_full_width', bp_core_avatar_dimension( 'full', 'width' ) );
    9681204}
    … …  
    9761212 */
    9771213function bp_core_avatar_full_height() {
     1214
     1215    /**
     1216     * Filters the 'full' avatar height setting.
     1217     *
     1218     * @since BuddyPress (1.5.0)
     1219     *
     1220     * @param int $value Value for the 'full' avatar height setting.
     1221     */
    9781222    return apply_filters( 'bp_core_avatar_full_height', bp_core_avatar_dimension( 'full', 'height' ) );
    9791223}
    … …  
    9871231 */
    9881232function bp_core_avatar_original_max_width() {
     1233
     1234    /**
     1235     * Filters the max width for original avatar uploads.
     1236     *
     1237     * @since BuddyPress (1.5.0)
     1238     *
     1239     * @param int $value Value for the max width.
     1240     */
    9891241    return apply_filters( 'bp_core_avatar_original_max_width', (int) buddypress()->avatar->original_max_width );
    9901242}
    … …  
    9981250 */
    9991251function bp_core_avatar_original_max_filesize() {
     1252
     1253    /**
     1254     * Filters the max filesize for original avatar uploads.
     1255     *
     1256     * @since BuddyPress (1.5.0)
     1257     *
     1258     * @param int $value Value for the max filesize.
     1259     */
    10001260    return apply_filters( 'bp_core_avatar_original_max_filesize', (int) buddypress()->avatar->original_max_filesize );
    10011261}
    … …  
    10251285    }
    10261286
     1287    /**
     1288     * Filters the URL of the 'full' default avatar.
     1289     *
     1290     * @since BuddyPress (1.5.0)
     1291     *
     1292     * @param string $avatar URL of the default avatar.
     1293     */
    10271294    return apply_filters( 'bp_core_avatar_default', $avatar );
    10281295}
    … …  
    10551322    }
    10561323
     1324    /**
     1325     * Filters the URL of the 'thumb' default avatar.
     1326     *
     1327     * @since BuddyPress (1.5.0)
     1328     *
     1329     * @param string $avatar URL of the default avatar.
     1330     */
    10571331    return apply_filters( 'bp_core_avatar_thumb', $avatar );
    10581332}
Note: See TracChangeset for help on using the changeset viewer.