Changeset 10012 for trunk/src/bp-core/bp-core-avatars.php
- Timestamp:
- 07/12/2015 12:49:36 AM (11 years ago)
- File:
-
- 1 edited
-
trunk/src/bp-core/bp-core-avatars.php (modified) (36 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/bp-core/bp-core-avatars.php
r9860 r10012 108 108 * add_filter( 'bp_core_fetch_avatar_no_grav', '__return_true' ); 109 109 * 110 * @param array $args {110 * @param array|string $args { 111 111 * An array of arguments. All arguments are technically optional; some 112 112 * will, if not provided, be auto-detected by bp_core_fetch_avatar(). This … … 114 114 * arguments. 115 115 * 116 * @type int|bool $item_id The numeric ID of the item for which you're117 * requestingan avatar (eg, a user ID). If no 'item_id' is present,118 * the function attempts to infer an ID from the 'object' + the119 * current context: if 'object' is 'user' and the current page is a120 * user page, 'item_id' will default to the displayed user ID; if121 * 'group' and on a group page, to the current group ID; if 'blog',122 * to the current blog's ID. If no 'item_id' can be determined in123 * this way, the function returns false. Default: false.124 * @type string $objectThe kind of object for which you're getting an125 * avatar. BuddyPress natively supports three options: 'user',126 * 'group', 'blog'; a plugin may register more. Default: 'user'.127 * @type string $typeWhen a new avatar is uploaded to BP, 'thumb' and128 * 'full' versions are saved. This parameter specifies whether you'd129 * like the 'full' or smaller 'thumb' avatar. Default: 'thumb'.116 * @type int|bool $item_id The numeric ID of the item for which you're requesting 117 * an avatar (eg, a user ID). If no 'item_id' is present, 118 * the function attempts to infer an ID from the 'object' + the 119 * current context: if 'object' is 'user' and the current page is a 120 * user page, 'item_id' will default to the displayed user ID; if 121 * 'group' and on a group page, to the current group ID; if 'blog', 122 * to the current blog's ID. If no 'item_id' can be determined in 123 * this way, the function returns false. Default: false. 124 * @type string $object The kind of object for which you're getting an 125 * avatar. BuddyPress natively supports three options: 'user', 126 * 'group', 'blog'; a plugin may register more. Default: 'user'. 127 * @type string $type When a new avatar is uploaded to BP, 'thumb' and 128 * 'full' versions are saved. This parameter specifies whether you'd 129 * like the 'full' or smaller 'thumb' avatar. Default: 'thumb'. 130 130 * @type string|bool $avatar_dir The name of the subdirectory where the 131 * requested avatar should be found. If no value is passed,132 * 'avatar_dir' is inferred from 'object': 'user' becomes 'avatars',133 * 'group' becomes 'group-avatars', 'blog' becomes 'blog-avatars'.134 * Remember that this string denotes a subdirectory of BP's main135 * avatar directory (usually based on {@link wp_upload_dir()}); it's a136 * string like 'group-avatars' rather than the full directory path.137 * Generally, it'll only be necessary to override the default value if138 * storing avatars in a non-default location. Defaults to false139 * (auto-detected).140 * @type int|bool $widthRequested avatar width. The unit is px. This value141 * is used to build the 'width' attribute for the <img> element. If142 * no value is passed, BP uses the global avatar width for this143 * avatar type. Default: false (auto-detected).144 * @type int|bool $heightRequested avatar height. The unit is px. This145 * value is used to build the 'height' attribute for the <img>146 * element. If no value is passed, BP uses the global avatar height147 * for this avatar type. Default: false (auto-detected).148 * @type string $classThe CSS class for the <img> element. Note that BP149 * uses the 'avatar' class fairly extensively in its default styling,150 * so if you plan to pass a custom value, consider appending it to151 * 'avatar' (eg 'avatar foo') rather than replacing it altogether.152 * Default: 'avatar'.153 * @type string|bool $css_id The CSS id for the <img> element.154 * Default: false.155 * @type string $titleThe title attribute for the <img> element.156 * Default: false.157 * @type string $altThe alt attribute for the <img> element. In BP, this158 * value is generally passed by the wrapper functions, where the data159 * necessary for concatenating the string is at hand; see160 * {@link bp_get_activity_avatar()} for an example. Default: ''.161 * @type string|bool $email An email to use in Gravatar queries. Unless162 * otherwise configured, BP uses Gravatar as a fallback for avatars163 * that are not provided locally. Gravatar's API requires using a hash164 * of the user's email address; this argument provides it. If not165 * provided, the function will infer it: for users, by getting the166 * user's email from the database, for groups/blogs, by concatenating167 * "{$item_id}-{$object}@{bp_get_root_domain()}". The user query adds168 * overhead, so it's recommended that wrapper functions provide a169 * value for 'email' when querying user IDs. Default: false.170 * @type bool $no_gravWhether to disable the default Gravatar fallback.171 * By default, BP will fall back on Gravatar when it cannot find a172 * local avatar. In some cases, this may be undesirable, in which173 * case 'no_grav' should be set to true. To disable Gravatar174 * fallbacks globally, see the 'bp_core_fetch_avatar_no_grav' filter.175 * Default: false.176 * @type bool $htmlWhether to return an <img> HTML element, vs a raw URL177 * to an avatar. If false, <img>-specific arguments (like 'css_id')178 * will be ignored. Default: true.131 * requested avatar should be found. If no value is passed, 132 * 'avatar_dir' is inferred from 'object': 'user' becomes 'avatars', 133 * 'group' becomes 'group-avatars', 'blog' becomes 'blog-avatars'. 134 * Remember that this string denotes a subdirectory of BP's main 135 * avatar directory (usually based on {@link wp_upload_dir()}); it's a 136 * string like 'group-avatars' rather than the full directory path. 137 * Generally, it'll only be necessary to override the default value if 138 * storing avatars in a non-default location. Defaults to false 139 * (auto-detected). 140 * @type int|bool $width Requested avatar width. The unit is px. This value 141 * is used to build the 'width' attribute for the <img> element. If 142 * no value is passed, BP uses the global avatar width for this 143 * avatar type. Default: false (auto-detected). 144 * @type int|bool $height Requested avatar height. The unit is px. This 145 * value is used to build the 'height' attribute for the <img> 146 * element. If no value is passed, BP uses the global avatar height 147 * for this avatar type. Default: false (auto-detected). 148 * @type string $class The CSS class for the <img> element. Note that BP 149 * uses the 'avatar' class fairly extensively in its default styling, 150 * so if you plan to pass a custom value, consider appending it to 151 * 'avatar' (eg 'avatar foo') rather than replacing it altogether. 152 * Default: 'avatar'. 153 * @type string|bool $css_id The CSS id for the <img> element. 154 * Default: false. 155 * @type string $title The title attribute for the <img> element. 156 * Default: false. 157 * @type string $alt The alt attribute for the <img> element. In BP, this 158 * value is generally passed by the wrapper functions, where the data 159 * necessary for concatenating the string is at hand; see 160 * {@link bp_get_activity_avatar()} for an example. Default: ''. 161 * @type string|bool $email An email to use in Gravatar queries. Unless 162 * otherwise configured, BP uses Gravatar as a fallback for avatars 163 * that are not provided locally. Gravatar's API requires using a hash 164 * of the user's email address; this argument provides it. If not 165 * provided, the function will infer it: for users, by getting the 166 * user's email from the database, for groups/blogs, by concatenating 167 * "{$item_id}-{$object}@{bp_get_root_domain()}". The user query adds 168 * overhead, so it's recommended that wrapper functions provide a 169 * value for 'email' when querying user IDs. Default: false. 170 * @type bool $no_grav Whether to disable the default Gravatar fallback. 171 * By default, BP will fall back on Gravatar when it cannot find a 172 * local avatar. In some cases, this may be undesirable, in which 173 * case 'no_grav' should be set to true. To disable Gravatar 174 * fallbacks globally, see the 'bp_core_fetch_avatar_no_grav' filter. 175 * Default: false. 176 * @type bool $html Whether to return an <img> HTML element, vs a raw URL 177 * to an avatar. If false, <img>-specific arguments (like 'css_id') 178 * will be ignored. Default: true. 179 179 * } 180 * 180 181 * @return string Formatted HTML <img> element, or raw avatar URL based on $html arg. 181 182 */ … … 530 531 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 ); 531 532 532 // ...or only the URL533 // ...or only the URL 533 534 } else { 534 535 … … 611 612 } 612 613 613 // No avatar was found, and we've been told not to use a gravatar.614 // No avatar was found, and we've been told not to use a gravatar. 614 615 } else { 615 616 … … 641 642 * Delete an existing avatar. 642 643 * 643 * @param array $args {644 * @param array|string $args { 644 645 * Array of function parameters. 645 646 * @type bool|int $item_id ID of the item whose avatar you're deleting. … … 721 722 722 723 /** 723 * Ajax delete an avatar for a given object and item id 724 * 725 * @since 726 * 727 * @return string ajson object containing success data if the avatar was deleted728 * error message otherwise724 * Ajax delete an avatar for a given object and item id. 725 * 726 * @since BuddyPress (2.3.0) 727 * 728 * @return string|null A json object containing success data if the avatar was deleted 729 * error message otherwise. 729 730 */ 730 731 function bp_avatar_ajax_delete() { … … 855 856 856 857 /** 857 * Ajax upload an avatar 858 * Ajax upload an avatar. 858 859 * 859 860 * @since BuddyPress (2.3.0) 860 861 * 861 * @return string ajson object containing success data if the upload succeeded862 * error message otherwise862 * @return string|null A json object containing success data if the upload succeeded 863 * error message otherwise. 863 864 */ 864 865 function bp_avatar_ajax_upload() { … … 923 924 } else { 924 925 /** 925 * Filter here to deal with other components 926 * Filter here to deal with other components. 926 927 * 927 928 * @since BuddyPress (2.3.0) 928 929 * 929 * @var array $bp_params the BuddyPress Ajax parameters 930 * @var array $bp_params the BuddyPress Ajax parameters. 930 931 */ 931 932 $bp_params = apply_filters( 'bp_core_avatar_ajax_upload_params', $bp_params ); … … 1008 1009 * @since BuddyPress (2.3.0) 1009 1010 * 1010 * @param string $data base64 encoded image. 1011 * @param int $item_id. 1011 * @param string $data Base64 encoded image. 1012 * @param int $item_id. 1013 * 1012 1014 * @return bool True on success, false on failure. 1013 1015 */ … … 1026 1028 } 1027 1029 1030 /** 1031 * Filters the Avatar folder directory. 1032 * 1033 * @since BuddyPress (2.3.0) 1034 * 1035 * @param string $avatar_dir Directory for storing avatars. 1036 * @param int $item_id ID of the item being acted on. 1037 * @param string $value Avatar type. 1038 * @param string $value Avatars word. 1039 */ 1028 1040 $avatar_folder_dir = apply_filters( 'bp_core_avatar_folder_dir', $avatar_dir . '/' . $item_id, $item_id, 'user', 'avatars' ); 1029 1041 … … 1043 1055 $crop_args = array( 'item_id' => $item_id, 'original_file' => $avatar_to_crop, 'crop_x' => 0, 'crop_y' => 0 ); 1044 1056 1057 /** 1058 * Fires if the new avatar was successfully captured. 1059 * 1060 * @since BuddyPress (2.3.0) 1061 */ 1045 1062 do_action( 'xprofile_avatar_uploaded' ); 1046 1063 … … 1064 1081 * crop_y - The vertical starting point of the crop 1065 1082 * 1066 * @param array $args {1083 * @param array|string $args { 1067 1084 * Array of function parameters. 1068 * @type string $object Object type of the item whose avatar you're 1069 * handling. 'user', 'group', 'blog', or custom. Default: 'user'. 1070 * @type string $avatar_dir Subdirectory where avatar should be stored. 1071 * Default: 'avatars'. 1072 * @type bool|int $item_id ID of the item that the avatar belongs to. 1073 * @type bool|string $original_file Absolute path to the original avatar 1074 * file. 1075 * @type int $crop_w Crop width. Default: the global 'full' avatar width, 1076 * as retrieved by bp_core_avatar_full_width(). 1077 * @type int $crop_h Crop height. Default: the global 'full' avatar height, 1078 * as retrieved by bp_core_avatar_full_height(). 1079 * @type int $crop_x The horizontal starting point of the crop. Default: 0. 1080 * @type int $crop_y The vertical starting point of the crop. Default: 0. 1085 * 1086 * @type string $object Object type of the item whose avatar you're 1087 * handling. 'user', 'group', 'blog', or custom. 1088 * Default: 'user'. 1089 * @type string $avatar_dir Subdirectory where avatar should be stored. 1090 * Default: 'avatars'. 1091 * @type bool|int $item_id ID of the item that the avatar belongs to. 1092 * @type bool|string $original_file Absolute path to the original avatar file. 1093 * @type int $crop_w Crop width. Default: the global 'full' avatar width, 1094 * as retrieved by bp_core_avatar_full_width(). 1095 * @type int $crop_h Crop height. Default: the global 'full' avatar height, 1096 * as retrieved by bp_core_avatar_full_height(). 1097 * @type int $crop_x The horizontal starting point of the crop. Default: 0. 1098 * @type int $crop_y The vertical starting point of the crop. Default: 0. 1081 1099 * } 1100 * 1082 1101 * @return bool True on success, false on failure. 1083 1102 */ … … 1103 1122 * 1104 1123 * @param bool $value Whether or not to crop. 1105 * @param array $r Array of parsed arguments for function 1124 * @param array $r Array of parsed arguments for function. 1106 1125 */ 1107 1126 if ( ! apply_filters( 'bp_core_pre_avatar_handle_crop', true, $r ) ) { … … 1122 1141 1123 1142 /** 1124 * Ajax set an avatar for a given object and item id 1143 * Ajax set an avatar for a given object and item id. 1125 1144 * 1126 1145 * @since BuddyPress (2.3.0) 1127 1146 * 1128 * @return string ajson object containing success data if the crop/capture succeeded1129 * error message otherwise1147 * @return string|null A json object containing success data if the crop/capture succeeded 1148 * error message otherwise. 1130 1149 */ 1131 1150 function bp_avatar_ajax_set() { … … 1241 1260 * Filters 'get_avatar'. 1242 1261 * 1243 * @param string $avatar The avatar path passed to 'get_avatar'. 1244 * @param int|string|object $user A user ID, email address, or comment object. 1245 * @param int $size Size of the avatar image ('thumb' or 'full'). 1246 * @param string $default URL to a default image to use if no avatar is available. 1247 * @param string $alt Alternate text to use in image tag. Default: ''. 1262 * @param string $avatar The avatar path passed to 'get_avatar'. 1263 * @param int|string|object $user A user ID, email address, or comment object. 1264 * @param int $size Size of the avatar image ('thumb' or 'full'). 1265 * @param string $default URL to a default image to use if no avatar is available. 1266 * @param string $alt Alternate text to use in image tag. Default: ''. 1267 * 1248 1268 * @return string BP avatar path, if found; else the original avatar path. 1249 1269 */ … … 1307 1327 * 1308 1328 * @param array $file The $_FILES array. 1329 * 1309 1330 * @return bool True if no errors are found. False if there are errors. 1310 1331 */ … … 1320 1341 * 1321 1342 * @param array $file The $_FILES array. 1343 * 1322 1344 * @return bool True if the avatar is under the size limit, otherwise false. 1323 1345 */ … … 1330 1352 1331 1353 /** 1332 * Get allowed avatar types 1333 * 1334 * @since 1354 * Get allowed avatar types. 1355 * 1356 * @since BuddyPress (2.3.0) 1335 1357 */ 1336 1358 function bp_core_get_allowed_avatar_types() { … … 1338 1360 1339 1361 /** 1340 * Use this filter to restrict image types1362 * Filters the list of allowed image types. 1341 1363 * 1342 1364 * @since BuddyPress (2.3.0) 1343 1365 * 1344 * @param array list of image types1366 * @param array $allowed_types List of image types. 1345 1367 */ 1346 1368 $avatar_types = (array) apply_filters( 'bp_core_get_allowed_avatar_types', $allowed_types ); … … 1356 1378 1357 1379 /** 1358 * Get allowed avatar mime types 1359 * 1360 * @since 1380 * Get allowed avatar mime types. 1381 * 1382 * @since BuddyPress (2.3.0) 1361 1383 */ 1362 1384 function bp_core_get_allowed_avatar_mimes() { … … 1382 1404 * 1383 1405 * @param array $file The $_FILES array. 1406 * 1384 1407 * @return bool True if the file extension is permitted, otherwise false. 1385 1408 */ … … 1399 1422 * @since BuddyPress (1.8.0) 1400 1423 * 1401 * @param string $type The variable we want to return from the $bp->avatars 1402 * object. Only 'upload_path' and 'url' are supported. Default: 'upload_path'. 1424 * @param string $type The variable we want to return from the $bp->avatars object. 1425 * Only 'upload_path' and 'url' are supported. Default: 'upload_path'. 1426 * 1403 1427 * @return string The avatar upload directory path. 1404 1428 */ … … 1474 1498 * Get the absolute upload path for the WP installation. 1475 1499 * 1476 * @uses bp_core_get_upload_dir() To get upload directory info 1500 * @uses bp_core_get_upload_dir() To get upload directory info. 1477 1501 * 1478 1502 * @return string Absolute path to WP upload directory. … … 1515 1539 * 1516 1540 * @param int $user_id ID of the user whose avatar is being checked. 1541 * 1517 1542 * @return bool True if the user has uploaded a local avatar. Otherwise false. 1518 1543 */ … … 1542 1567 * @since BuddyPress (1.5.0) 1543 1568 * 1544 * @param string $type Dimension type you're fetching dimensions for. 'thumb'1545 * or 'full'. Default: 'thumb'.1569 * @param string $type Dimension type you're fetching dimensions for. 'thumb' 1570 * or 'full'. Default: 'thumb'. 1546 1571 * @param string $h_or_w Which dimension is being fetched. 'height' or 'width'. 1547 * Default: 'height'. 1548 * @return int $dim The dimension. 1572 * Default: 'height'. 1573 * 1574 * @return int|bool $dim The dimension. 1549 1575 */ 1550 1576 function bp_core_avatar_dimension( $type = 'thumb', $h_or_w = 'height' ) { … … 1557 1583 * @since BuddyPress (1.5.0) 1558 1584 * 1559 * @param int 1560 * @param string $type The type of avatar whose dimensions are requested. Default 'thumb'.1561 * @param string $h_or_w The dimension parameter being requested. Default 'height'.1585 * @param int|bool $dim Dimension setting for the type. 1586 * @param string $type The type of avatar whose dimensions are requested. Default 'thumb'. 1587 * @param string $h_or_w The dimension parameter being requested. Default 'height'. 1562 1588 */ 1563 1589 return apply_filters( 'bp_core_avatar_dimension', $dim, $type, $h_or_w ); … … 1603 1629 1604 1630 /** 1605 * Get the 'full' avatar width setting 1631 * Get the 'full' avatar width setting. 1606 1632 * 1607 1633 * @since BuddyPress (1.5.0) … … 1683 1709 * @since BuddyPress (1.5.0) 1684 1710 * 1685 * @param string $type 'local' if the fallback should be the locally-hosted 1686 * version of the mystery-man, 'gravatar' if the fallback should be 1687 * Gravatar's version. Default: 'gravatar'. 1711 * @param string $type 'local' if the fallback should be the locally-hosted version 1712 * of the mystery-man, 'gravatar' if the fallback should be 1713 * Gravatar's version. Default: 'gravatar'. 1714 * 1688 1715 * @return string The URL of the default avatar. 1689 1716 */ … … 1720 1747 * @since BuddyPress (1.5.0) 1721 1748 * 1722 * @param string $type 'local' if the fallback should be the locally-hosted 1723 * version of the mystery-man, 'gravatar' if the fallback should be 1724 * Gravatar's version. Default: 'gravatar'. 1749 * @param string $type 'local' if the fallback should be the locally-hosted version 1750 * of the mystery-man, 'gravatar' if the fallback should be 1751 * Gravatar's version. Default: 'gravatar'. 1752 * 1725 1753 * @return string The URL of the default avatar thumb. 1726 1754 */ … … 1750 1778 1751 1779 /** 1752 * Reset the week parameter of the WordPress main query if needed 1780 * Reset the week parameter of the WordPress main query if needed. 1753 1781 * 1754 1782 * When cropping an avatar, a $_POST['w'] var is sent, setting the 'week' 1755 1783 * parameter of the WordPress main query to this posted var. To avoid 1756 * notices, we need to make sure this 'week' query var is reset to 0 1784 * notices, we need to make sure this 'week' query var is reset to 0. 1757 1785 * 1758 1786 * @since BuddyPress (2.2.0) 1759 1787 * 1760 * @param WP_Query $posts_query the main query object 1788 * @param WP_Query|null $posts_query the main query object. 1789 * 1761 1790 * @uses bp_is_group_create() 1762 1791 * @uses bp_is_group_admin_page() … … 1793 1822 1794 1823 /** 1795 * Checks whether Avatar UI should be loaded 1824 * Checks whether Avatar UI should be loaded. 1796 1825 * 1797 1826 * @since BuddyPress (2.3.0) 1798 1827 * 1799 * @return bool True if Avatar UI should load, false otherwise 1828 * @return bool True if Avatar UI should load, false otherwise. 1800 1829 */ 1801 1830 function bp_avatar_is_front_edit() { … … 1829 1858 * @since BuddyPress (2.3.0) 1830 1859 * 1831 * @ var bool whether to load the Avatar UI1860 * @param bool whether to load the Avatar UI. 1832 1861 */ 1833 1862 return apply_filters( 'bp_avatar_is_front_edit', $retval ); … … 1835 1864 1836 1865 /** 1837 * Checks whether the Webcam Avatar UI part should be loaded 1866 * Checks whether the Webcam Avatar UI part should be loaded. 1838 1867 * 1839 1868 * @since BuddyPress (2.3.0) … … 1867 1896 * by returning false. 1868 1897 * 1869 * @since 1870 * 1871 * @ var bool whether to load Webcam Avatar UI part1898 * @since BuddyPress (2.3.0) 1899 * 1900 * @param bool whether to load Webcam Avatar UI part. 1872 1901 */ 1873 1902 return apply_filters( 'bp_avatar_use_webcam', true ); … … 1875 1904 1876 1905 /** 1877 * Template function to load the Avatar UI javascript templates 1906 * Template function to load the Avatar UI javascript templates. 1878 1907 * 1879 1908 * @since BuddyPress (2.3.0) … … 1888 1917 1889 1918 /** 1890 * Trick to check if the theme's BuddyPress templates are up to date 1919 * Trick to check if the theme's BuddyPress templates are up to date. 1891 1920 * 1892 1921 * If the "avatar templates" are not including the new template tag, this will
Note: See TracChangeset
for help on using the changeset viewer.