Changeset 25508


Ignore:
Timestamp:
Nov 17, 2013, 5:57:04 PM (7 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.