Ignore:
Timestamp:
Nov 18, 2013, 11:02:17 AM (10 years ago)
Author:
mistic100
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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.