Changeset 25508


Ignore:
Timestamp:
11/17/13 17:57:04 (6 years ago)
Author:
mistic100
Message:

feature 2999 : documentation of include/functions_category.inc.php

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/functions_category.inc.php

    r25425 r25508  
    2323 
    2424/** 
    25  * Provides functions to handle categories. 
    26  * 
    27  * 
    28  */ 
     25 * @package functions\category 
     26 */ 
     27 
     28 
     29/** 
     30 * Callback used for sorting by global_rank 
     31 */ 
     32function global_rank_compare($a, $b) 
     33{ 
     34  return strnatcasecmp($a['global_rank'], $b['global_rank']); 
     35} 
     36 
     37/** 
     38 * Callback used for sorting by rank 
     39 */ 
     40function rank_compare($a, $b) 
     41{ 
     42  return $a['rank'] - $b['rank']; 
     43} 
    2944 
    3045/** 
    3146 * Is the category accessible to the connected user ? 
    32  * 
    33  * Note : if the user is not authorized to see this category, page creation 
    34  * ends (exit command in this function) 
    35  * 
    36  * @param int category id to verify 
    37  * @return void 
     47 * If the user is not authorized to see this category, script exits 
     48 * 
     49 * @param int $category_id 
    3850 */ 
    3951function check_restrictions($category_id) 
     
    4961} 
    5062 
     63/** 
     64 * Returns template vars for main categories menu. 
     65 * 
     66 * @return array[] 
     67 */ 
    5168function get_categories_menu() 
    5269{ 
     
    144161} 
    145162 
    146  
    147 /** 
    148  * Retrieve informations about a category in the database 
    149  * 
    150  * Returns an array with following keys : 
    151  * 
    152  *  - comment 
    153  *  - dir : directory, might be empty for virtual categories 
    154  *  - name : an array with indexes from 0 (lowest cat name) to n (most 
    155  *           uppercat name findable) 
    156  *  - nb_images 
    157  *  - id_uppercat 
    158  *  - site_id 
    159  *  - 
    160  * 
    161  * @param int category id 
     163/** 
     164 * Retrieves informations about a category. 
     165 * 
     166 * @param int $id 
    162167 * @return array 
    163168 */ 
    164 function get_cat_info( $id ) 
     169function get_cat_info($id) 
    165170{ 
    166171  $query = ' 
     
    213218} 
    214219 
    215  
    216  
    217 // returns an array of image orders available for users/visitors 
     220/** 
     221 * Returns an array of image orders available for users/visitors. 
     222 * Each entry is an array containing 
     223 *  0: name 
     224 *  1: SQL ORDER command 
     225 *  2: visiblity (true or false) 
     226 * 
     227 * @return array[] 
     228 */ 
    218229function get_category_preferred_image_orders() 
    219230{ 
     
    236247} 
    237248 
     249/** 
     250 * Assign a template var useable with {html_options} from a list of categories 
     251 * 
     252 * @param array[] $categories (at least id,name,global_rank,uppercats for each) 
     253 * @param int[] $selected ids of selected items 
     254 * @param string $blockname variable name in template 
     255 * @param bool $fullname full breadcrumb or not 
     256 */ 
    238257function display_select_categories($categories, 
    239258                                   $selecteds, 
     
    275294} 
    276295 
    277 function display_select_cat_wrapper($query, $selecteds, $blockname, 
     296/** 
     297 * Same as display_select_categories but categories are ordered by rank 
     298 * @see display_select_categories() 
     299 */ 
     300function display_select_cat_wrapper($query, 
     301                                    $selecteds, 
     302                                    $blockname, 
    278303                                    $fullname = true) 
    279304{ 
     
    284309 
    285310/** 
    286  * returns all subcategory identifiers of given category ids 
    287  * 
    288  * @param array ids 
    289  * @return array 
     311 * Returns all subcategory identifiers of given category ids 
     312 * 
     313 * @param int[] $ids 
     314 * @return int[] 
    290315 */ 
    291316function get_subcat_ids($ids) 
     
    314339} 
    315340 
    316 /** finds a matching category id from a potential list of permalinks 
    317  * @param array permalinks example: holiday holiday/france holiday/france/paris 
    318  * @param int idx - output of the index in $permalinks that matches 
    319  * return category id or null if no match 
    320  */ 
    321 function get_cat_id_from_permalinks( $permalinks, &$idx ) 
     341/** 
     342 * Finds a matching category id from a potential list of permalinks 
     343 * 
     344 * @param string[] $permalinks 
     345 * @param int $idx filled with the index in $permalinks that matches 
     346 * @return int|null 
     347 */ 
     348function get_cat_id_from_permalinks($permalinks, &$idx) 
    322349{ 
    323350  $in = ''; 
     
    360387} 
    361388 
    362 function global_rank_compare($a, $b) 
    363 { 
    364   return strnatcasecmp($a['global_rank'], $b['global_rank']); 
    365 } 
    366  
    367 function rank_compare($a, $b) 
    368 { 
    369   return $a['rank'] - $b['rank']; 
    370 } 
    371  
    372 /** 
    373  * returns display text for information images of category 
    374  * 
    375  * @param array categories 
     389/** 
     390 * Returns display text for images counter of category 
     391 * 
     392 * @param int $cat_nb_images nb images directly in category 
     393 * @param int $cat_count_images nb images in category (including subcats) 
     394 * @param int $cat_count_categories nb subcats 
     395 * @param bool $short_message if true append " in this album" 
     396 * @param string $separator 
    376397 * @return string 
    377398 */ 
    378 function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_categories, $short_message = true, $Separator = '\n') 
     399function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_categories, $short_message = true, $separator = '\n') 
    379400{ 
    380401  $display_text = ''; 
     
    384405    if ($cat_nb_images > 0 and $cat_nb_images < $cat_count_images) 
    385406    { 
    386       $display_text.= get_display_images_count($cat_nb_images, $cat_nb_images, 0, $short_message, $Separator).$Separator; 
     407      $display_text.= get_display_images_count($cat_nb_images, $cat_nb_images, 0, $short_message, $separator).$separator; 
    387408      $cat_count_images-= $cat_nb_images; 
    388409      $cat_nb_images = 0; 
     
    395416    { 
    396417      //no descendant categories or descendants do not contain images 
    397       if (! $short_message) 
     418      if (!$short_message) 
    398419      { 
    399420        $display_text.= ' '.l10n('in this album'); 
     
    410431 
    411432/** 
    412  * Find a random photo among all photos below a given album in the tree (not 
    413  * only photo directly associated to the album but also to sub-albums) 
    414  * 
    415  * we need $category['uppercats'], $category['id'], $category['count_images'] 
     433 * Find a random photo among all photos inside an album (including sub-albums) 
     434 * 
     435 * @param array $category (at least id,uppercats,count_images) 
     436 * @param bool $recursive 
     437 * @return int|null 
    416438 */ 
    417439function get_random_image_in_category($category, $recursive=true) 
     
    459481} 
    460482 
    461  
    462483?> 
Note: See TracChangeset for help on using the changeset viewer.