Skip to content

Commit

Permalink
feature 2999 : documentation of include/functions_category.inc.php
Browse files Browse the repository at this point in the history 
git-svn-id: http://piwigo.org/svn/trunk@25508 68402e56-0260-453c-a942-63ccdbb3a9ee
  • Loading branch information
@mistic100
mistic100 committed Nov 17, 2013
1 parent 5e2b2f4 commit 6bd462d
Showing 1 changed file with 75 additions and 54 deletions.
129 changes: 75 additions & 54 deletions include/functions_category.inc.php
View file
Expand Up @@ -22,19 +22,31 @@
// +-----------------------------------------------------------------------+

/**
* Provides functions to handle categories.
*
*
* @package functions\category
*/


/**
* Callback used for sorting by global_rank
*/
function global_rank_compare($a, $b)
{
return strnatcasecmp($a['global_rank'], $b['global_rank']);
}

/**
* Callback used for sorting by rank
*/
function rank_compare($a, $b)
{
return $a['rank'] - $b['rank'];
}

/**
* Is the category accessible to the connected user ?
* If the user is not authorized to see this category, script exits
*
* Note : if the user is not authorized to see this category, page creation
* ends (exit command in this function)
*
* @param int category id to verify
* @return void
* @param int $category_id
*/
function check_restrictions($category_id)
{
Expand All @@ -48,6 +60,11 @@ function check_restrictions($category_id)
}
}

/**
* Returns template vars for main categories menu.
*
* @return array[]
*/
function get_categories_menu()
{
global $page, $user, $filter, $conf;
Expand Down Expand Up @@ -143,25 +160,13 @@ function get_categories_menu()
return $cats;
}


/**
* Retrieve informations about a category in the database
*
* Returns an array with following keys :
*
* - comment
* - dir : directory, might be empty for virtual categories
* - name : an array with indexes from 0 (lowest cat name) to n (most
* uppercat name findable)
* - nb_images
* - id_uppercat
* - site_id
* -
* Retrieves informations about a category.
*
* @param int category id
* @param int $id
* @return array
*/
function get_cat_info( $id )
function get_cat_info($id)
{
$query = '
SELECT *
Expand Down Expand Up @@ -212,9 +217,15 @@ function get_cat_info( $id )
return $cat;
}



// returns an array of image orders available for users/visitors
/**
* Returns an array of image orders available for users/visitors.
* Each entry is an array containing
* 0: name
* 1: SQL ORDER command
* 2: visiblity (true or false)
*
* @return array[]
*/
function get_category_preferred_image_orders()
{
global $conf, $page;
Expand All @@ -235,6 +246,14 @@ function get_category_preferred_image_orders()
));
}

/**
* Assign a template var useable with {html_options} from a list of categories
*
* @param array[] $categories (at least id,name,global_rank,uppercats for each)
* @param int[] $selected ids of selected items
* @param string $blockname variable name in template
* @param bool $fullname full breadcrumb or not
*/
function display_select_categories($categories,
$selecteds,
$blockname,
Expand Down Expand Up @@ -274,7 +293,13 @@ function display_select_categories($categories,
$template->assign( $blockname.'_selected', $selecteds);
}

function display_select_cat_wrapper($query, $selecteds, $blockname,
/**
* Same as display_select_categories but categories are ordered by rank
* @see display_select_categories()
*/
function display_select_cat_wrapper($query,
$selecteds,
$blockname,
$fullname = true)
{
$categories = array_from_query($query);
Expand All @@ -283,10 +308,10 @@ function display_select_cat_wrapper($query, $selecteds, $blockname,
}

/**
* returns all subcategory identifiers of given category ids
* Returns all subcategory identifiers of given category ids
*
* @param array ids
* @return array
* @param int[] $ids
* @return int[]
*/
function get_subcat_ids($ids)
{
Expand All @@ -313,12 +338,14 @@ function get_subcat_ids($ids)
return array_from_query($query, 'id');
}

/** finds a matching category id from a potential list of permalinks
* @param array permalinks example: holiday holiday/france holiday/france/paris
* @param int idx - output of the index in $permalinks that matches
* return category id or null if no match
/**
* Finds a matching category id from a potential list of permalinks
*
* @param string[] $permalinks
* @param int $idx filled with the index in $permalinks that matches
* @return int|null
*/
function get_cat_id_from_permalinks( $permalinks, &$idx )
function get_cat_id_from_permalinks($permalinks, &$idx)
{
$in = '';
foreach($permalinks as $permalink)
Expand Down Expand Up @@ -359,31 +386,25 @@ function get_cat_id_from_permalinks( $permalinks, &$idx )
return null;
}

function global_rank_compare($a, $b)
{
return strnatcasecmp($a['global_rank'], $b['global_rank']);
}

function rank_compare($a, $b)
{
return $a['rank'] - $b['rank'];
}

/**
* returns display text for information images of category
* Returns display text for images counter of category
*
* @param array categories
* @param int $cat_nb_images nb images directly in category
* @param int $cat_count_images nb images in category (including subcats)
* @param int $cat_count_categories nb subcats
* @param bool $short_message if true append " in this album"
* @param string $separator
* @return string
*/
function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_categories, $short_message = true, $Separator = '\n')
function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_categories, $short_message = true, $separator = '\n')
{
$display_text = '';

if ($cat_count_images > 0)
{
if ($cat_nb_images > 0 and $cat_nb_images < $cat_count_images)
{
$display_text.= get_display_images_count($cat_nb_images, $cat_nb_images, 0, $short_message, $Separator).$Separator;
$display_text.= get_display_images_count($cat_nb_images, $cat_nb_images, 0, $short_message, $separator).$separator;
$cat_count_images-= $cat_nb_images;
$cat_nb_images = 0;
}
Expand All @@ -394,7 +415,7 @@ function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_
if ($cat_count_categories == 0 or $cat_nb_images == $cat_count_images)
{
//no descendant categories or descendants do not contain images
if (! $short_message)
if (!$short_message)
{
$display_text.= ' '.l10n('in this album');
}
Expand All @@ -409,10 +430,11 @@ function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_
}

/**
* Find a random photo among all photos below a given album in the tree (not
* only photo directly associated to the album but also to sub-albums)
* Find a random photo among all photos inside an album (including sub-albums)
*
* we need $category['uppercats'], $category['id'], $category['count_images']
* @param array $category (at least id,uppercats,count_images)
* @param bool $recursive
* @return int|null
*/
function get_random_image_in_category($category, $recursive=true)
{
Expand Down Expand Up @@ -458,5 +480,4 @@ function get_random_image_in_category($category, $recursive=true)
return $image_id;
}


?>

0 comments on commit 6bd462d

Please sign in to comment.