1<?php 2# MantisBT - A PHP based bugtracking system 3 4# MantisBT is free software: you can redistribute it and/or modify 5# it under the terms of the GNU General Public License as published by 6# the Free Software Foundation, either version 2 of the License, or 7# (at your option) any later version. 8# 9# MantisBT is distributed in the hope that it will be useful, 10# but WITHOUT ANY WARRANTY; without even the implied warranty of 11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12# GNU General Public License for more details. 13# 14# You should have received a copy of the GNU General Public License 15# along with MantisBT. If not, see <http://www.gnu.org/licenses/>. 16 17/** 18 * Prepare API 19 * 20 * Handles preparation of strings prior to be printed or stored. 21 * 22 * @package CoreAPI 23 * @subpackage PrepareAPI 24 * @copyright Copyright 2000 - 2002 Kenzaburo Ito - kenito@300baud.org 25 * @copyright Copyright 2002 MantisBT Team - mantisbt-dev@lists.sourceforge.net 26 * @link http://www.mantisbt.org 27 * 28 * @uses access_api.php 29 * @uses config_api.php 30 * @uses constant_inc.php 31 * @uses string_api.php 32 * @uses user_api.php 33 * @uses version_api.php 34 */ 35 36require_api( 'access_api.php' ); 37require_api( 'config_api.php' ); 38require_api( 'constant_inc.php' ); 39require_api( 'string_api.php' ); 40require_api( 'user_api.php' ); 41require_api( 'version_api.php' ); 42 43/** 44 * Return a ready-to-use mailto: URL. 45 * 46 * No validation is performed on the e-mail address, it is the caller's 47 * responsibility to ensure it is valid and not empty. 48 * 49 * @param string $p_email Target e-mail address 50 * @param string $p_subject Optional e-mail subject 51 * 52 * @return string 53 */ 54function prepare_mailto_url ( $p_email, $p_subject = '' ) { 55 # If we apply string_url() to the whole mailto: link then the @ gets 56 # turned into a %40 and you can't right click in browsers to use the 57 # Copy Email Address functionality. 58 if( $p_subject ) { 59 # URL-encoding the subject is required otherwise special characters 60 # (ampersand for example) will truncate the text 61 $p_subject = '?subject=' . string_url( $p_subject ); 62 } 63 $t_mailto = 'mailto:' . $p_email . $p_subject; 64 65 return string_attribute( $t_mailto ); 66} 67 68/** 69 * return an HTML link with mailto: href. 70 * 71 * If user does not have access level required to see email addresses, the 72 * function will only return the display text (with tooltip if provided). 73 * 74 * @param string $p_email Email address to prepare. 75 * @param string $p_text Display text for the hyperlink. 76 * @param string $p_subject Optional e-mail subject 77 * @param string $p_tooltip Optional tooltip to show. 78 * @param boolean $p_show_as_button If true, show link as button with envelope 79 * icon, otherwise display a plain-text link. 80 * 81 * @return string 82 */ 83function prepare_email_link( $p_email, $p_text, $p_subject = '', $p_tooltip ='', $p_show_as_button = false ) { 84 $t_text = string_display_line( $p_text ); 85 if( !is_blank( $p_tooltip ) && $p_tooltip != $p_text ) { 86 $t_tooltip = ' title="' . string_display_line( $p_tooltip ) . '"'; 87 } else { 88 $t_tooltip = ''; 89 } 90 91 if( !access_has_project_level( config_get( 'show_user_email_threshold' ) ) ) { 92 return $t_tooltip ? '<a' . $t_tooltip . '>' . $t_text . '</a>' : $t_text; 93 } 94 95 $t_mailto = prepare_mailto_url( $p_email, $p_subject ); 96 97 if( $p_show_as_button ) { 98 $t_class = ' class="noprint blue zoom-130"'; 99 $t_text = icon_get( 'fa-envelope-o', 'bigger-115' ) 100 . ( $t_text ? " $t_text" : '' ); 101 } else { 102 $t_class = ''; 103 } 104 105 return sprintf( '<a href="%s"%s%s>%s</a>', 106 $t_mailto, 107 $t_tooltip, 108 $t_class, 109 $t_text 110 ); 111} 112 113/** 114 * Prepares the name of the user given the id. 115 * Also can make it a link to user info page. 116 * @param integer $p_user_id A valid user identifier. 117 * @param boolean $p_link Whether to include an html link 118 * @return string 119 */ 120function prepare_user_name( $p_user_id, $p_link = true ) { 121 # Catch a user_id of NO_USER (like when a handler hasn't been assigned) 122 if( NO_USER == $p_user_id ) { 123 return ''; 124 } 125 126 $t_username = user_get_username( $p_user_id ); 127 $t_name = user_get_name( $p_user_id ); 128 if( $t_username != $t_name ) { 129 $t_tooltip = ' title="' . string_attribute( $t_username ) . '"'; 130 } else { 131 $t_tooltip = ''; 132 } 133 134 $t_name = string_display_line( $t_name ); 135 136 if( user_exists( $p_user_id ) && user_get_field( $p_user_id, 'enabled' ) ) { 137 if( $p_link ) { 138 return '<a' . $t_tooltip . ' href="' . string_sanitize_url( 'view_user_page.php?id=' . $p_user_id, true ) . '">' . $t_name . '</a>'; 139 } else { 140 return '<span ' . $t_tooltip . '>' . $t_name . '</span>'; 141 } 142 } 143 144 return '<del ' . $t_tooltip . '>' . $t_name . '</del>'; 145} 146 147/** 148 * A function that prepares the version string for outputting to the user on view / print issue pages. 149 * This function would add the version date, if appropriate. 150 * 151 * @param integer $p_project_id The project id to use as context. 152 * @param integer $p_version_id The version id. If false then this method will return an empty string. 153 * @param boolean|null $p_show_project Whether to include the project name or not, 154 * null means include the project if different from current context. 155 * @return string The formatted version string. 156 */ 157function prepare_version_string( $p_project_id, $p_version_id, $p_show_project = null ) { 158 if( $p_version_id === false ) { 159 return ''; 160 } 161 162 $t_version_text = version_full_name( $p_version_id, $p_show_project, $p_project_id ); 163 164 if( access_has_project_level( config_get( 'show_version_dates_threshold' ), $p_project_id ) ) { 165 $t_short_date_format = config_get( 'short_date_format' ); 166 167 $t_version = version_cache_row( $p_version_id ); 168 if( 1 == $t_version['released'] ) { 169 $t_version_text .= ' (' . date( $t_short_date_format, $t_version['date_order'] ) . ')'; 170 } 171 } 172 173 return $t_version_text; 174} 175 176/** 177 * Prepares avatar for raw outputting (only avatar image). 178 * 179 * @param Avatar $p_avatar An instance of class Avatar. 180 * @param string $p_class_prefix CSS class prefix to add to the avatar's surrounding div and to the img. 181 * The CSS classes to implement will be named [$p_class_prefix]-avatar_container-[$p_size] and 182 * [$p_class_prefix]-avatar-[$p_size]. 183 * @param integer $p_size Image maximum size. 184 * @return string the HTML string of the avatar. 185 */ 186function prepare_raw_avatar( $p_avatar, $p_class_prefix, $p_size) { 187 if( $p_avatar === null ) { 188 return ''; 189 } 190 191 $t_image = htmlspecialchars( $p_avatar->image ); 192 $t_text = htmlspecialchars( $p_avatar->text ); 193 194 $t_avatar_class = $p_class_prefix . '-avatar' . '-' . $p_size; 195 return '<img class="' . $t_avatar_class . '" src="' . $t_image . '" alt="' . 196 $t_text . '" />'; 197} 198 199/** 200 * Prepares avatar for outputting. 201 * 202 * @param Avatar $p_avatar An instance of class Avatar. 203 * @param string $p_class_prefix CSS class prefix to add to the avatar's surrounding div and to the img. 204 * The CSS classes to implement will be named [$p_class_prefix]-avatar-container-[$p_size] and 205 * [$p_class_prefix]-avatar-[$p_size]. 206 * @param integer $p_size Image maximum size. 207 * @return string the HTML string of the avatar. 208 */ 209function prepare_avatar( $p_avatar, $p_class_prefix, $p_size ) { 210 if( $p_avatar === null ) { 211 return ''; 212 } 213 214 $t_link = htmlspecialchars( $p_avatar->link ); 215 216 $t_container_class = $p_class_prefix . '-avatar-container' . '-' . $p_size; 217 return '<div class="' . $t_container_class . '">' . 218 '<a rel="nofollow" href="' . $t_link . '">' . 219 prepare_raw_avatar( $p_avatar, $p_class_prefix, $p_size ) . 220 '</a></div>'; 221} 222 223