Changeset 8196

Show
Ignore:
Timestamp:
06/26/08 15:55:33 (5 months ago)
Author:
ryan
Message:

phpdoc for shortcodes from jacobsantos. fixes #7184

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/shortcodes.php

    r8054 r8196  
    11<?php 
    2  
    3 /* 
    4  
    5 An API for creating shortcode tags that support attributes and enclosed content, such as: 
    6  
    7 [shortcode /] 
    8 [shortcode foo="bar" baz="bing" /] 
    9 [shortcode foo="bar"]content[/shortcode] 
    10  
    11 tag and attrbute parsing regexp code based on the Textpattern tag parser. 
    12  
    13 To apply shortcode tags to content: 
    14  
    15 $out = do_shortcode($content); 
    16  
    17 Simplest example of a shortcode tag using the API: 
    18  
    19 // [footag foo="bar"] 
    20 function footag_func($atts) { 
    21     return "foo = {$atts[foo]}"; 
    22 } 
    23 add_shortcode('footag', 'footag_func'); 
    24  
    25 Example with nice attribute defaults: 
    26  
    27 // [bartag foo="bar"] 
    28 function bartag_func($atts) { 
    29     extract(shortcode_atts(array( 
    30         'foo' => 'no foo', 
    31         'baz' => 'default baz', 
    32     ), $atts)); 
    33  
    34     return "foo = {$foo}"; 
    35 } 
    36 add_shortcode('bartag', 'bartag_func'); 
    37  
    38 Example with enclosed content: 
    39  
    40 // [baztag]content[/baztag] 
    41 function baztag_func($atts, $content='') { 
    42     return "content = $content"; 
    43 } 
    44 add_shortcode('baztag', 'baztag_func'); 
    45  
    46 */ 
    47  
     2/** 
     3 * WordPress API for creating bbcode like tags or what WordPress calls 
     4 * "shortcodes." The tag and attribute parsing or regular expression code is 
     5 * based on the Textpattern tag parser. 
     6 * 
     7 * A few examples are below: 
     8 * 
     9 * [shortcode /] 
     10 * [shortcode foo="bar" baz="bing" /] 
     11 * [shortcode foo="bar"]content[/shortcode] 
     12 * 
     13 * Shortcode tags support attributes and enclosed content, but does not entirely 
     14 * support inline shortcodes in other shortcodes. You will have to call the 
     15 * shortcode parser in your function to account for that. 
     16 * 
     17 * {@internal 
     18 * Please be aware that the above note was made during the beta of WordPress 2.6 
     19 * and in the future may not be accurate. Please update the note when it is no 
     20 * longer the case.}} 
     21 * 
     22 * To apply shortcode tags to content: 
     23 * 
     24 * <code> 
     25 * $out = do_shortcode($content); 
     26 * </code> 
     27 * 
     28 * @link http://codex.wordpress.org/Shortcode_API 
     29 * 
     30 * @package WordPress 
     31 * @subpackage Shortcodes 
     32 * @since 2.5 
     33 */ 
     34 
     35/** 
     36 * Container for storing shortcode tags and their hook to call for the shortcode 
     37 * 
     38 * @since 2.5 
     39 * @name $shortcode_tags 
     40 * @var array 
     41 * @global array $shortcode_tags 
     42 */ 
    4843$shortcode_tags = array(); 
    4944 
     45/** 
     46 * Add hook for shortcode tag. 
     47 * 
     48 * There can only be one hook for each shortcode. Which means that if another 
     49 * plugin has a similar shortcode, it will override yours or yours will override 
     50 * theirs depending on which order the plugins are included and/or ran. 
     51 *  
     52 * Simplest example of a shortcode tag using the API: 
     53 * 
     54 * <code> 
     55 * // [footag foo="bar"] 
     56 * function footag_func($atts) { 
     57 *  return "foo = {$atts[foo]}"; 
     58 * } 
     59 * add_shortcode('footag', 'footag_func'); 
     60 * </code> 
     61 * 
     62 * Example with nice attribute defaults: 
     63 * 
     64 * <code> 
     65 * // [bartag foo="bar"] 
     66 * function bartag_func($atts) { 
     67 *  extract(shortcode_atts(array( 
     68 *      'foo' => 'no foo', 
     69 *      'baz' => 'default baz', 
     70 *  ), $atts)); 
     71 * 
     72 *  return "foo = {$foo}"; 
     73 * } 
     74 * add_shortcode('bartag', 'bartag_func'); 
     75 * </code> 
     76 * 
     77 * Example with enclosed content: 
     78 * 
     79 * <code> 
     80 * // [baztag]content[/baztag] 
     81 * function baztag_func($atts, $content='') { 
     82 *  return "content = $content"; 
     83 * } 
     84 * add_shortcode('baztag', 'baztag_func'); 
     85 * </code> 
     86 * 
     87 * @since 2.5 
     88 * @uses $shortcode_tags 
     89 * 
     90 * @param string $tag Shortcode tag to be searched in post content. 
     91 * @param callable $func Hook to run when shortcode is found. 
     92 */ 
    5093function add_shortcode($tag, $func) { 
    5194    global $shortcode_tags; 
    …… 
    5598} 
    5699 
     100/** 
     101 * Removes hook for shortcode. 
     102 * 
     103 * @since 2.5 
     104 * @uses $shortcode_tags 
     105 * 
     106 * @param string $tag shortcode tag to remove hook for. 
     107 */ 
    57108function remove_shortcode($tag) { 
    58109    global $shortcode_tags; 
    …… 
    61112} 
    62113 
     114/** 
     115 * Clear all shortcodes. 
     116 * 
     117 * This function is simple, it clears all of the shortcode tags by replacing the 
     118 * shortcodes global by a empty array. This is actually a very efficient method 
     119 * for removing all shortcodes. 
     120 * 
     121 * @since 2.5 
     122 * @uses $shortcode_tags 
     123 */ 
    63124function remove_all_shortcodes() { 
    64125    global $shortcode_tags; 
    …… 
    67128} 
    68129 
     130/** 
     131 * Search content for shortcodes and filter shortcodes through their hooks. 
     132 * 
     133 * If there are no shortcode tags defined, then the content will be returned 
     134 * without any filtering. This might cause issues when plugins are disabled but 
     135 * the shortcode will still show up in the post or content. 
     136 * 
     137 * @since 2.5 
     138 * @uses $shortcode_tags 
     139 * @uses get_shortcode_regex() Gets the search pattern for searching shortcodes. 
     140 * 
     141 * @param string $content Content to search for shortcodes 
     142 * @return string Content with shortcodes filtered out. 
     143 */ 
    69144function do_shortcode($content) { 
    70145    global $shortcode_tags; 
    …… 
    77152} 
    78153 
     154/** 
     155 * Retrieve the shortcode regular expression for searching. 
     156 * 
     157 * The regular expression combines the shortcode tags in the regular expression 
     158 * in a regex class. 
     159 * 
     160 * @since 2.5 
     161 * @uses $shortcode_tags 
     162 * 
     163 * @return string The shortcode search regular expression 
     164 */ 
    79165function get_shortcode_regex() { 
    80166    global $shortcode_tags; 
    …… 
    85171} 
    86172 
     173/** 
     174 * Regular Expression callable for do_shortcode() for calling shortcode hook. 
     175 * 
     176 * @since 2.5 
     177 * @access private 
     178 * @uses $shortcode_tags 
     179 * 
     180 * @param array $m Regular expression match array 
     181 * @return mixed False on failure. 
     182 */ 
    87183function do_shortcode_tag($m) { 
    88184    global $shortcode_tags; 
    …… 
    100196} 
    101197 
     198/** 
     199 * Retrieve all attributes from the shortcodes tag. 
     200 * 
     201 * The attributes list has the attribute name as the key and the value of the 
     202 * attribute as the value in the key/value pair. This allows for easier 
     203 * retrieval of the attributes, since all attributes have to be known. 
     204 * 
     205 * @since 2.5 
     206 * 
     207 * @param string $text  
     208 * @return array List of attributes and their value. 
     209 */ 
    102210function shortcode_parse_atts($text) { 
    103211    $atts = array(); 
    …… 
    123231} 
    124232 
     233/** 
     234 * Combine user attributes with known attributes and fill in defaults when needed. 
     235 * 
     236 * The pairs should be considered to be all of the attributes which are 
     237 * supported by the caller and given as a list. The returned attributes will 
     238 * only contain the attributes in the $pairs list. 
     239 * 
     240 * If the $atts list has unsupported attributes, then they will be ignored and 
     241 * removed from the final returned list. 
     242 * 
     243 * @since 2.5 
     244 * 
     245 * @param array $pairs Entire list of supported attributes and their defaults. 
     246 * @param array $atts User defined attributes in shortcode tag. 
     247 * @return array Combined and filtered attribute list. 
     248 */ 
    125249function shortcode_atts($pairs, $atts) { 
    126250    $atts = (array)$atts; 
    …… 
    135259} 
    136260 
    137 /*  
    138  * stip all the shortcodes from a post's content  
    139  * returns the content without shortcodes 
    140  */ 
    141 function strip_shortcodes( $content ) {  
    142      
     261/** 
     262 * Remove all shortcode tags from the given content. 
     263 * 
     264 * @since 2.5 
     265 * @uses $shortcode_tags 
     266 * 
     267 * @param string $content Content to remove shortcode tags. 
     268 * @return string Content without shortcode tags. 
     269 */ 
     270function strip_shortcodes( $content ) { 
    143271    global $shortcode_tags; 
    144272 
    …… 
    149277 
    150278    return preg_replace('/'.$pattern.'/s', '', $content); 
    151      
    152279} 
    153280