Changeset 25548


Ignore:
Timestamp:
11/18/13 11:02:17 (6 years ago)
Author:
mistic100
Message:

feature 2999: documentation of functions\comment|cookie|filter|html

Location:
trunk/include
Files:
4 edited

Legend:

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

    r25360 r25548  
    2222// +-----------------------------------------------------------------------+ 
    2323 
    24 //returns string action to perform on a new comment: validate, moderate, reject 
     24/** 
     25 * @package functions\comment 
     26 */ 
     27  
     28 
     29add_event_handler('user_comment_check', 'user_comment_check', 
     30  EVENT_HANDLER_PRIORITY_NEUTRAL, 2); 
     31 
     32/** 
     33 * Does basic check on comment and returns action to perform. 
     34 * This method is called by a trigger_event() 
     35 * 
     36 * @param string $action before check 
     37 * @param array $comment 
     38 * @return string validate, moderate, reject 
     39 */ 
    2540function user_comment_check($action, $comment) 
    2641{ 
     
    5570} 
    5671 
    57  
    58 add_event_handler('user_comment_check', 'user_comment_check', 
    59   EVENT_HANDLER_PRIORITY_NEUTRAL, 2); 
    60  
    61 /** 
    62  * Tries to insert a user comment in the database and returns one of : 
    63  * validate, moderate, reject 
    64  * @param array comm contains author, content, image_id 
    65  * @param string key secret key sent back to the browser 
    66  * @param array infos out array of messages 
    67  */ 
    68 function insert_user_comment( &$comm, $key, &$infos ) 
     72/** 
     73 * Tries to insert a user comment and returns action to perform. 
     74 * 
     75 * @param array $comm 
     76 * @param string $key secret key sent back to the browser 
     77 * @param array $infos output array of error messages 
     78 * @return string validate, moderate, reject 
     79 */ 
     80function insert_user_comment(&$comm, $key, &$infos) 
    6981{ 
    7082  global $conf, $user; 
     
    252264    } 
    253265  } 
     266 
    254267  return $comment_action; 
    255268} 
    256269 
    257270/** 
    258  * Tries to delete a user comment in the database 
    259  * only admin can delete all comments 
    260  * other users can delete their own comments 
    261  * so to avoid a new sql request we add author in where clause 
    262  * 
    263  * @param int or array of int comment_id 
     271 * Tries to delete a (or more) user comment. 
     272 *    only admin can delete all comments 
     273 *    other users can delete their own comments 
     274 * 
     275 * @param int|int[] $comment_id 
     276 * @return bool false if nothing deleted 
    264277 */ 
    265278function delete_user_comment($comment_id) 
     
    291304                  )); 
    292305    trigger_action('user_comment_deletion', $comment_id); 
    293   } 
    294 } 
    295  
    296 /** 
    297  * Tries to update a user comment in the database 
    298  * only admin can update all comments 
    299  * users can edit their own comments if admin allow them 
    300  * so to avoid a new sql request we add author in where clause 
    301  * 
    302  * @param comment_id 
    303  * @param post_key 
    304  * @param content 
     306 
     307    return true; 
     308  } 
     309 
     310  return false; 
     311} 
     312 
     313/** 
     314 * Tries to update a user comment 
     315 *    only admin can update all comments 
     316 *    users can edit their own comments if admin allow them 
     317 * 
     318 * @param array $comment 
     319 * @param string $post_key secret key sent back to the browser 
     320 * @return string validate, moderate, reject 
    305321 */ 
    306322 
     
    398414} 
    399415 
     416/** 
     417 * Notifies admins about updated or deleted comment. 
     418 * Only used when no validation is needed, otherwise pwg_mail_notification_admins() is used. 
     419 * 
     420 * @param string $action edit, delete 
     421 * @param array $comment 
     422 */ 
    400423function email_admin($action, $comment) 
    401424{ 
     
    431454} 
    432455 
     456/** 
     457 * Returns the author id of a comment 
     458 * 
     459 * @param int $comment_id 
     460 * @param bool $die_on_error 
     461 * @return int 
     462 */ 
    433463function get_comment_author_id($comment_id, $die_on_error=true) 
    434464{ 
     
    458488 
    459489/** 
    460  * Tries to validate a user comment in the database 
    461  * @param int or array of int comment_id 
     490 * Tries to validate a user comment. 
     491 * 
     492 * @param int|int[] $comment_id 
    462493 */ 
    463494function validate_user_comment($comment_id) 
     
    480511} 
    481512 
    482  
     513/** 
     514 * Clears cache of nb comments for all users 
     515 */ 
    483516function invalidate_user_cache_nb_comments() 
    484517{ 
    485518  global $user; 
     519 
    486520  unset($user['nb_available_comments']); 
     521 
    487522  $query = ' 
    488523UPDATE '.USER_CACHE_TABLE.' 
    489   SET nb_available_comments = NULL'; 
     524  SET nb_available_comments = NULL 
     525;'; 
    490526  pwg_query($query); 
    491527} 
  • trunk/include/functions_cookie.inc.php

    r19703 r25548  
    2222// +-----------------------------------------------------------------------+ 
    2323 
    24 // cookie_path returns the path to use for the Piwigo cookie. 
    25 // If Piwigo is installed on : 
    26 // http://domain.org/meeting/gallery/category.php 
    27 // cookie_path will return : "/meeting/gallery" 
     24/** 
     25 * @package functions\cookie 
     26 */ 
     27 
     28 
     29/** 
     30 * Returns the path to use for the Piwigo cookie. 
     31 * If Piwigo is installed on : 
     32 * http://domain.org/meeting/gallery/ 
     33 * it will return : "/meeting/gallery" 
     34 * 
     35 * @return string 
     36 */ 
    2837function cookie_path() 
    2938{ 
     
    8493 
    8594/** 
    86  * persistently stores a variable in pwg cookie 
    87  * @return boolean true on success 
    88  * @see pwg_get_cookie_var 
     95 * Persistently stores a variable in pwg cookie. 
     96 * Set $value to null to delete the cookie. 
     97 * 
     98 * @param string $car 
     99 * @param mixed $value 
     100 * @param int|null $expire 
     101 * @return bool 
    89102 */ 
    90103function pwg_set_cookie_var($var, $value, $expire=null) 
     
    105118 
    106119/** 
    107  * retrieves the value of a persistent variable in pwg cookie 
     120 * Retrieves the value of a persistent variable in pwg cookie 
     121 * @see pwg_set_cookie_var 
     122 * 
     123 * @param string $var 
     124 * @param mixed $default 
    108125 * @return mixed 
    109  * @see pwg_set_cookie_var 
    110126 */ 
    111127function pwg_get_cookie_var($var, $default = null) 
  • trunk/include/functions_filter.inc.php

    r19703 r25548  
    2222// +-----------------------------------------------------------------------+ 
    2323 
     24/** 
     25 * @package functions\filter 
     26 */ 
    2427 
    2528 
    2629/** 
    27  * update data of categories with filtered values 
     30 * Updates data of categories with filtered values 
    2831 * 
    29  * @param array list of categories 
    30  * @return null 
     32 * @param array $cats 
    3133 */ 
    3234function update_cats_with_filtered_data(&$cats) 
  • trunk/include/functions_html.inc.php

    r25425 r25548  
    2323 
    2424/** 
    25  * returns the list of categories as a HTML string 
    26  * 
    27  * categories string returned contains categories as given in the input 
     25 * @package functions\html 
     26 */ 
     27 
     28 
     29/** 
     30 * Generates breadcrumb from categories list. 
     31 * Categories string returned contains categories as given in the input 
    2832 * array $cat_informations. $cat_informations array must be an array 
    2933 * of array( id=>?, name=>?, permalink=>?). If url input parameter is null, 
    3034 * returns only the categories name without links. 
    3135 * 
    32  * @param array cat_informations 
    33  * @param string url 
    34  * @return string 
    35  */ 
    36 function get_cat_display_name($cat_informations, $url = '') 
     36 * @param array $cat_informations 
     37 * @param string|null $url 
     38 * @return string 
     39 */ 
     40function get_cat_display_name($cat_informations, $url='') 
    3741{ 
    3842  global $conf; 
     
    8892 
    8993/** 
    90  * returns the list of categories as a HTML string, with cache of names 
    91  * 
    92  * categories string returned contains categories as given in the input 
    93  * array $cat_informations. $uppercats is the list of category ids to 
    94  * display in the right order. If url input parameter is empty, returns only 
    95  * the categories name without links. 
    96  * 
    97  * @param string uppercats 
    98  * @param string url 
     94 * Generates breadcrumb from categories list using a cache. 
     95 * @see get_cat_display_name() 
     96 * 
     97 * @param string $uppercats 
     98 * @param string|null $url 
     99 * @param bool $single_link 
     100 * @param string|null $link_class 
    99101 * @return string 
    100102 */ 
     
    177179 
    178180/** 
    179  * returns HTMLized comment contents retrieved from database 
    180  * 
    181  * newlines becomes br tags, _word_ becomes underline, /word/ becomes 
    182  * italic, *word* becomes bolded 
    183  * 
    184  * @param string content 
     181 * Generates breadcrumb for a category. 
     182 * @see get_cat_display_name() 
     183 * 
     184 * @param int $cat_id 
     185 * @param string|null $url 
     186 * @return string 
     187 */ 
     188function get_cat_display_name_from_id($cat_id, $url = '') 
     189{ 
     190  $cat_info = get_cat_info($cat_id); 
     191  return get_cat_display_name($cat_info['upper_names'], $url); 
     192} 
     193 
     194/** 
     195 * Apply basic markdown transformations to a text. 
     196 * newlines becomes br tags 
     197 * _word_ becomes underline 
     198 * /word/ becomes italic 
     199 * *word* becomes bolded 
     200 * urls becomes a tags 
     201 * 
     202 * @param string $content 
    185203 * @return string 
    186204 */ 
     
    209227  $content = preg_replace($pattern, $replacement, $content); 
    210228 
     229  // TODO : add a trigger 
     230 
    211231  return $content; 
    212 } 
    213  
    214 function get_cat_display_name_from_id($cat_id, $url = '') 
    215 { 
    216   $cat_info = get_cat_info($cat_id); 
    217   return get_cat_display_name($cat_info['upper_names'], $url); 
    218232} 
    219233 
     
    267281} 
    268282 
     283/** 
     284 * Callback used for sorting by name. 
     285 */ 
    269286function name_compare($a, $b) 
    270287{ 
     
    272289} 
    273290 
     291/** 
     292 * Callback used for sorting by name (slug) with cache. 
     293 */ 
    274294function tag_alpha_compare($a, $b) 
    275295{ 
     
    288308 
    289309/** 
    290  * exits the current script (either exit or redirect) 
     310 * Exits the current script (or redirect to login page if not logged). 
    291311 */ 
    292312function access_denied() 
     
    315335 
    316336/** 
    317  * exits the current script with 403 code 
    318  * @param string msg a message to display 
    319  * @param string alternate_url redirect to this url 
     337 * Exits the current script with 403 code. 
     338 * TODO : nice display if $template loaded 
     339 * 
     340 * @param string $msg 
     341 * @param string|null $alternate_url redirect to this url 
    320342 */ 
    321343function page_forbidden($msg, $alternate_url=null) 
     
    332354 
    333355/** 
    334  * exits the current script with 400 code 
    335  * @param string msg a message to display 
    336  * @param string alternate_url redirect to this url 
     356 * Exits the current script with 400 code. 
     357 * TODO : nice display if $template loaded 
     358 * 
     359 * @param string $msg 
     360 * @param string|null $alternate_url redirect to this url 
    337361 */ 
    338362function bad_request($msg, $alternate_url=null) 
     
    349373 
    350374/** 
    351  * exits the current script with 404 code when a page cannot be found 
    352  * @param string msg a message to display 
    353  * @param string alternate_url redirect to this url 
     375 * Exits the current script with 404 code. 
     376 * TODO : nice display if $template loaded 
     377 * 
     378 * @param string $msg 
     379 * @param string|null $alternate_url redirect to this url 
    354380 */ 
    355381function page_not_found($msg, $alternate_url=null) 
     
    366392 
    367393/** 
    368  * exits the current script with 500 http code 
    369  * this method can be called at any time (does not use template/language/user etc...) 
    370  * @param string msg a message to display 
     394 * Exits the current script with 500 code. 
     395 * TODO : nice display if $template loaded 
     396 * 
     397 * @param string $msg 
     398 * @param string|null $title 
     399 * @param bool $show_trace 
    371400 */ 
    372401function fatal_error($msg, $title=null, $show_trace=true) 
     
    409438} 
    410439 
    411 /* returns the title to be displayed above thumbnails on tag page 
     440/** 
     441 * Returns the breadcrumb to be displayed above thumbnails on tag page. 
     442 * 
     443 * @return string 
    412444 */ 
    413445function get_tags_content_title() 
     
    458490 
    459491/** 
    460   Sets the http status header (200,401,...) 
     492 * Sets the http status header (200,401,...) 
     493 * @param int $code 
     494 * @param string $text for exotic http codes 
    461495 */ 
    462496function set_status_header($code, $text='') 
     
    487521} 
    488522 
    489 /** returns the category comment for rendering in html textual mode (subcatify) 
    490  * this is an event handler. don't call directly 
     523/** 
     524 * Returns the category comment for rendering in html textual mode (subcatify) 
     525 * This method is called by a trigger_action() 
     526 * 
     527 * @param string $desc 
     528 * @return string 
    491529 */ 
    492530function render_category_literal_description($desc) 
     
    495533} 
    496534 
    497 /*event handler for menu*/ 
    498 function register_default_menubar_blocks( $menu_ref_arr ) 
     535/** 
     536 * Add known menubar blocks. 
     537 * This method is called by a trigger_event() 
     538 * 
     539 * @param BlockManager[] $menu_ref_arr 
     540 */ 
     541function register_default_menubar_blocks($menu_ref_arr) 
    499542{ 
    500543  $menu = & $menu_ref_arr[0]; 
     
    510553 
    511554/** 
     555 * Returns display name for an element. 
     556 * Returns 'name' if exists of name from 'file'. 
     557 * 
     558 * @param array $info at least file or name 
     559 * @return string 
    512560 */ 
    513561function render_element_name($info) 
    514562{ 
    515   $name = $info['name']; 
    516   if (!empty($name)) 
    517   { 
    518     $name = trigger_event('render_element_name', $name); 
    519     return $name; 
    520   } 
    521  
     563  if (!empty($info['name'])) 
     564  { 
     565    return trigger_event('render_element_name', $info['name']); 
     566  } 
    522567  return get_name_from_file($info['file']); 
    523568} 
    524569 
     570/** 
     571 * Returns display description for an element. 
     572 * 
     573 * @param array $info at least comment 
     574 * @param string $param used to identify the trigger 
     575 * @return string 
     576 */ 
    525577function render_element_description($info, $param='') 
    526578{ 
    527   $comment = $info['comment']; 
    528   if (!empty($comment)) 
    529   { 
    530     $comment = trigger_event('render_element_description', $comment, $param); 
    531     return $comment; 
     579  if (!empty($info['comment'])) 
     580  { 
     581    return trigger_event('render_element_description', $info['comment'], $param); 
    532582  } 
    533583  return ''; 
     
    535585 
    536586/** 
    537  * returns the title of the thumbnail based on photo properties 
    538  */ 
    539 function get_thumbnail_title($info, $title, $comment) 
     587 * Add info to the title of the thumbnail based on photo properties. 
     588 * 
     589 * @param array $info hit, rating_score, nb_comments 
     590 * @param string $title 
     591 * @param string $comment 
     592 * @return string 
     593 */ 
     594function get_thumbnail_title($info, $title, $comment='') 
    540595{ 
    541596  global $conf, $user; 
     
    571626  $title = htmlspecialchars(strip_tags($title)); 
    572627  $title = trigger_event('get_thumbnail_title', $title, $info); 
     628 
    573629  return $title; 
    574630} 
    575631 
    576 /** optional event handler to protect src image urls */ 
     632/** 
     633 * Event handler to protect src image urls. 
     634 * 
     635 * @param string $url 
     636 * @param SrcImage $src_image 
     637 * @return string 
     638 */ 
    577639function get_src_image_url_protection_handler($url, $src_image) 
    578640{ 
     
    580642} 
    581643 
    582 /** optional event handler to protect element urls */ 
     644/** 
     645 * Event handler to protect element urls. 
     646 * 
     647 * @param string $url 
     648 * @param array $infos id, path 
     649 * @return string 
     650 */ 
    583651function get_element_url_protection_handler($url, $infos) 
    584652{ 
     
    595663} 
    596664 
    597  
     665/** 
     666 * Sends to the template all messages stored in $page and in the session. 
     667 */ 
    598668function flush_page_messages() 
    599669{ 
Note: See TracChangeset for help on using the changeset viewer.