Changeset 25548 for trunk/include


Ignore:
Timestamp:
Nov 18, 2013, 11:02:17 AM (10 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.