core/excel_api.php

   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  * Excel API
  19  *
  20  * @package CoreAPI
  21  * @subpackage ExcelAPI
  22  * @copyright Copyright (C) 2000 - 2002  Kenzaburo Ito - kenito@300baud.org
  23  * @copyright Copyright (C) 2002 - 2010  MantisBT Team - mantisbt-dev@lists.sourceforge.net
  24  * @link http://www.mantisbt.org
  25  *
  26  * @uses authentication_api.php
  27  * @uses bug_api.php
  28  * @uses category_api.php
  29  * @uses columns_api.php
  30  * @uses config_api.php
  31  * @uses constant_inc.php
  32  * @uses custom_field_api.php
  33  * @uses helper_api.php
  34  * @uses lang_api.php
  35  * @uses project_api.php
  36  * @uses user_api.php
  37  */
  38
  39 require_api( 'authentication_api.php' );
  40 require_api( 'bug_api.php' );
  41 require_api( 'category_api.php' );
  42 require_api( 'columns_api.php' );
  43 require_api( 'config_api.php' );
  44 require_api( 'constant_inc.php' );
  45 require_api( 'custom_field_api.php' );
  46 require_api( 'helper_api.php' );
  47 require_api( 'lang_api.php' );
  48 require_api( 'project_api.php' );
  49 require_api( 'user_api.php' );
  50
  51 /**
  52  * A method that returns the header for an Excel Xml file.
  53  *
  54  * @param $p_worksheet_title  The worksheet title.
  55  * @returns the header Xml.
  56  */
  57 function excel_get_header( $p_worksheet_title ) {
  58         $p_worksheet_title = preg_replace( '/[\/:*?"<>|]/', '', $p_worksheet_title );
  59         return "<?xml version=\"1.0\" encoding=\"UTF-8\"?><?mso-application progid=\"Excel.Sheet\"?>
  60  <Workbook xmlns=\"urn:schemas-microsoft-com:office:spreadsheet\"
  61  xmlns:x=\"urn:schemas-microsoft-com:office:excel\"
  62  xmlns:ss=\"urn:schemas-microsoft-com:office:spreadsheet\"
  63  xmlns:html=\"http://www.w3.org/TR/REC-html40\">\n<Worksheet ss:Name=\"" . urlencode( $p_worksheet_title ) . "\">\n<Table>\n<Column ss:Index=\"1\" ss:AutoFitWidth=\"0\" ss:Width=\"110\"/>\n";
  64 }
  65
  66 /**
  67  * A method that returns the footer for an Excel Xml file.
  68  * @returns the footer xml.
  69  */
  70 function excel_get_footer() {
  71         return "</Table>\n</Worksheet></Workbook>\n";
  72 }
  73
  74 /**
  75  * Generates a cell XML for a column title.
  76  * @returns The cell xml.
  77  */
  78 function excel_format_column_title( $p_column_title ) {
  79         return '<Cell><Data ss:Type="String">' . $p_column_title . '</Data></Cell>';
  80 }
  81
  82 /**
  83  * Generates the xml for the start of an Excel row.
  84  * @returns The Row tag.
  85  */
  86 function excel_get_start_row() {
  87         return '<Row>';
  88 }
  89
  90 /**
  91  * Generates the xml for the end of an Excel row.
  92  * @returns The Row end tag.
  93  */
  94 function excel_get_end_row() {
  95         return '</Row>';
  96 }
  97
  98 /**
  99  * Gets an Xml Row that contains all column titles.
 100  * @returns The xml row.
 101  */
 102 function excel_get_titles_row() {
 103         $t_columns = excel_get_columns();
 104         $t_ret = '<Row>';
 105
 106         foreach( $t_columns as $t_column ) {
 107                 $t_custom_field = column_get_custom_field_name( $t_column );
 108                 if( $t_custom_field !== null ) {
 109                         $t_ret .= excel_format_column_title( lang_get_defaulted( $t_custom_field ) );
 110                 } else {
 111                         $t_column_title = column_get_title( $t_column );
 112                         $t_ret .= excel_format_column_title( $t_column_title );
 113                 }
 114         }
 115
 116         $t_ret .= '</Row>';
 117
 118         return $t_ret;
 119 }
 120
 121 /**
 122  * Gets the download file name for the Excel export.  If 'All Projects' selected, default to <username>,
 123  * otherwise default to <projectname>.
 124 * @returns file name without extension
 125 */
 126 function excel_get_default_filename() {
 127         $t_current_project_id = helper_get_current_project();
 128
 129         if( ALL_PROJECTS == $t_current_project_id ) {
 130                 $t_filename = user_get_name( auth_get_current_user_id() );
 131         } else {
 132                 $t_filename = project_get_field( $t_current_project_id, 'name' );
 133         }
 134
 135         return $t_filename;
 136 }
 137
 138 /**
 139  * Escapes the specified column value and includes it in a Cell Xml.
 140  * @param $p_value The value
 141  * @returns The Cell Xml.
 142  */
 143 function excel_prepare_string( $p_value ) {
 144         $t_type = is_numeric( $p_value ) ? 'Number' : 'String';
 145
 146         $t_ret = "<Cell><Data ss:Type=\"$t_type\">";
 147         $t_value = $p_value;
 148         $t_value = str_replace( "\n", '&#10;', $t_value );
 149         $t_value = str_replace( '<', '&lt;', $t_value );
 150         $t_value = str_replace( '>', '&gt;', $t_value );
 151         $t_ret .= $t_value;
 152         $t_ret .= "</Data></Cell>\n";
 153
 154         return $t_ret;
 155 }
 156
 157 /**
 158  * Gets the columns to be included in the Excel Xml export.
 159  * @returns column names.
 160  */
 161 function excel_get_columns() {
 162         $t_columns = helper_get_columns_to_view( COLUMNS_TARGET_EXCEL_PAGE );
 163         return $t_columns;
 164 }
 165
 166 #
 167 # Formatting Functions
 168 #
 169 # Names for formatting functions are excel_format_*, where * corresponds to the
 170 # field name as return get excel_get_columns() and by the filter api.
 171 #
 172 /**
 173  * Gets the formatted bug id value.
 174  * @param $p_bug_id  The bug id to be formatted.
 175  * @returns The bug id prefixed with 0s.
 176  */
 177 function excel_format_id( $p_bug_id ) {
 178         return excel_prepare_string( bug_format_id( $p_bug_id ) );
 179 }
 180
 181 /**
 182  * Gets the formatted project id value.
 183  * @param $p_project_id The project id.
 184  * @returns The project name.
 185  */
 186 function excel_format_project_id( $p_project_id ) {
 187         return excel_prepare_string( project_get_name( $p_project_id ) );
 188 }
 189
 190 /**
 191  * Gets the formatted reporter id value.
 192  * @param $p_reporter_id The reporter id.
 193  * @returns The reporter user name.
 194  */
 195 function excel_format_reporter_id( $p_reporter_id ) {
 196         return excel_prepare_string( user_get_name( $p_reporter_id ) );
 197 }
 198
 199 /**
 200  * Gets the formatted number of bug notes.
 201  * @param $p_bugnotes_count  The number of bug notes.
 202  * @returns The number of bug notes.
 203  */
 204 function excel_format_bugnotes_count( $p_bugnotes_count ) {
 205         return excel_prepare_string( $p_bugnotes_count );
 206 }
 207
 208 /**
 209  * Gets the formatted handler id.
 210  * @param $p_handler_id The handler id.
 211  * @returns The handler user name or empty string.
 212  */
 213 function excel_format_handler_id( $p_handler_id ) {
 214         if( $p_handler_id > 0 ) {
 215                 return excel_prepare_string( user_get_name( $p_handler_id ) );
 216         } else {
 217                 return excel_prepare_string( '' );
 218         }
 219 }
 220
 221 /**
 222  * Gets the formatted priority.
 223  * @param $p_priority priority id.
 224  * @returns the priority text.
 225  */
 226 function excel_format_priority( $p_priority ) {
 227         return excel_prepare_string( get_enum_element( 'priority', $p_priority ) );
 228 }
 229
 230 /**
 231  * Gets the formatted severity.
 232  * @param $p_severity severity id.
 233  * @returns the severity text.
 234  */
 235 function excel_format_severity( $p_severity ) {
 236         return excel_prepare_string( get_enum_element( 'severity', $p_severity ) );
 237 }
 238
 239 /**
 240  * Gets the formatted reproducibility.
 241  * @param $p_reproducibility reproducibility id.
 242  * @returns the reproducibility text.
 243  */
 244 function excel_format_reproducibility( $p_reproducibility ) {
 245         return excel_prepare_string( get_enum_element( 'reproducibility', $p_reproducibility ) );
 246 }
 247
 248 /**
 249  * Gets the formatted view state,
 250  * @param $p_view_state The view state (e.g. public vs. private)
 251  * @returns The view state
 252  */
 253 function excel_format_view_state( $p_view_state ) {
 254         return excel_prepare_string( get_enum_element( 'view_state', $p_view_state ) );
 255 }
 256
 257 /**
 258  * Gets the formatted projection.
 259  * @param $p_projection projection id.
 260  * @returns the projection text.
 261  */
 262 function excel_format_projection( $p_projection ) {
 263         return excel_prepare_string( get_enum_element( 'projection', $p_projection ) );
 264 }
 265
 266 /**
 267  * Gets the formatted eta.
 268  * @param $p_eta eta id.
 269  * @returns the eta text.
 270  */
 271 function excel_format_eta( $p_eta ) {
 272         return excel_prepare_string( get_enum_element( 'eta', $p_eta ) );
 273 }
 274
 275 /**
 276  * Gets the status field.
 277  * @param $p_status The status field.
 278  * @returns the formatted status.
 279  */
 280 function excel_format_status( $p_status ) {
 281         return excel_prepare_string( get_enum_element( 'status', $p_status ) );
 282 }
 283
 284 /**
 285  * Gets the resolution field.
 286  * @param $p_resolution The resolution field.
 287  * @returns the formatted resolution.
 288  */
 289 function excel_format_resolution( $p_resolution ) {
 290         return excel_prepare_string( get_enum_element( 'resolution', $p_resolution ) );
 291 }
 292
 293 /**
 294  * Gets the formatted version.
 295  * @param $p_version The product version
 296  * @returns the product version.
 297  */
 298 function excel_format_version( $p_version ) {
 299         return excel_prepare_string( $p_version );
 300 }
 301
 302 /**
 303  * Gets the formatted fixed in version.
 304  * @param $p_fixed_in_version The product fixed in version
 305  * @returns the fixed in version.
 306  */
 307 function excel_format_fixed_in_version( $p_fixed_in_version ) {
 308         return excel_prepare_string( $p_fixed_in_version );
 309 }
 310
 311 /**
 312  * Gets the formatted target version.
 313  * @param $p_target_version The target version
 314  * @returns the target version.
 315  */
 316 function excel_format_target_version( $p_target_version ) {
 317         return excel_prepare_string( $p_target_version );
 318 }
 319
 320 /**
 321  * Gets the formatted category.
 322  * @param $p_category The category
 323  * @returns the category.
 324  */
 325 function excel_format_category_id( $p_category_id ) {
 326         return excel_prepare_string( category_full_name( $p_category_id, false ) );
 327 }
 328
 329 /**
 330  * Gets the formatted operating system.
 331  * @param $p_os The operating system
 332  * @returns the operating system.
 333  */
 334 function excel_format_os( $p_os ) {
 335         return excel_prepare_string( $p_os );
 336 }
 337
 338 /**
 339  * Gets the formatted operating system build (version).
 340  * @param $p_os The operating system build (version)
 341  * @returns the operating system build (version)
 342  */
 343 function excel_format_os_build( $p_os_build ) {
 344         return excel_prepare_string( $p_os_build );
 345 }
 346
 347 /**
 348  * Gets the formatted product build,
 349  * @param $p_build The product build
 350  * @returns the product build.
 351  */
 352 function excel_format_build( $p_build ) {
 353         return excel_prepare_string( $p_build );
 354 }
 355
 356 /**
 357  * Gets the formatted platform,
 358  * @param $p_platform The platform
 359  * @returns the platform.
 360  */
 361 function excel_format_platform( $p_platform ) {
 362         return excel_prepare_string( $p_platform );
 363 }
 364
 365 /**
 366  * Gets the formatted date submitted.
 367  * @param $p_date_submitted The date submitted
 368  * @returns the date submitted in short date format.
 369  */
 370 function excel_format_date_submitted( $p_date_submitted ) {
 371         return excel_prepare_string( date( config_get( 'short_date_format' ), $p_date_submitted ) );
 372 }
 373
 374 /**
 375  * Gets the formatted date last updated.
 376  * @param $p_last_updated The date last updated.
 377  * @returns the date last updated in short date format.
 378  */
 379 function excel_format_last_updated( $p_last_updated ) {
 380         return excel_prepare_string( date( config_get( 'short_date_format' ), $p_last_updated ) );
 381 }
 382
 383 /**
 384  * Gets the summary field.
 385  * @param $p_summary The summary.
 386  * @returns the formatted summary.
 387  */
 388 function excel_format_summary( $p_summary ) {
 389         return excel_prepare_string( $p_summary );
 390 }
 391
 392 /**
 393  * Gets the formatted selection.
 394  * @param $p_selection The selection value
 395  * @returns An formatted empty string.
 396  */
 397 function excel_format_selection( $p_param ) {
 398         return excel_prepare_string( '' );
 399 }
 400
 401 /**
 402  * Gets the formatted description field.
 403  * @param $p_description The description.
 404  * @returns The formatted description (multi-line).
 405  */
 406 function excel_format_description( $p_description ) {
 407         return excel_prepare_string( $p_description );
 408 }
 409
 410 /**
 411  * Gets the formatted 'steps to reproduce' field.
 412  * @param $p_steps_to_reproduce The steps to reproduce.
 413  * @returns The formatted steps to reproduce (multi-line).
 414  */
 415 function excel_format_steps_to_reproduce( $p_steps_to_reproduce ) {
 416         return excel_prepare_string( $p_steps_to_reproduce );
 417 }
 418
 419 /**
 420  * Gets the formatted 'additional information' field.
 421  * @param $p_additional_information The additional information field.
 422  * @returns The formatted additional information (multi-line).
 423  */
 424 function excel_format_additional_information( $p_additional_information ) {
 425         return excel_prepare_string( $p_additional_information );
 426 }
 427
 428 /**
 429  * Gets the formatted value for the specified issue id, project and custom field.
 430  * @param $p_issue_id The issue id.
 431  * @param $p_project_id The project id.
 432  * @param $p_custom_field The custom field name (without 'custom_' prefix).
 433  * @returns The custom field value.
 434  */
 435 function excel_format_custom_field( $p_issue_id, $p_project_id, $p_custom_field ) {
 436         $t_field_id = custom_field_get_id_from_name( $p_custom_field );
 437
 438         if( $t_field_id === false ) {
 439                 return excel_prepare_string( '@' . $p_custom_field . '@' );
 440         }
 441
 442         if( custom_field_is_linked( $t_field_id, $p_project_id ) ) {
 443                 $t_def = custom_field_get_definition( $t_field_id );
 444                 return excel_prepare_string( string_custom_field_value( $t_def, $t_field_id, $p_issue_id ) );
 445         }
 446
 447         // field is not linked to project
 448         return excel_prepare_string( '' );
 449 }