WordPress.org

Make WordPress Core

Ticket #7184: shortcodes.phpdoc.8194.diff

File shortcodes.phpdoc.8194.diff, 7.9 KB (added by jacobsantos, 10 years ago)

PHPdoc inline documentation for shortcodes.php based off of r8194

  • shortcodes.php

     
    11<?php
     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 */
    234
    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 
     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;
    5295
     
    5497                $shortcode_tags[$tag] = $func;
    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;
    59110
    60111        unset($shortcode_tags[$tag]);
    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;
    65126
    66127        $shortcode_tags = array();
    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;
    71146
     
    76151        return preg_replace_callback('/'.$pattern.'/s', 'do_shortcode_tag', $content);
    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;
    81167        $tagnames = array_keys($shortcode_tags);
     
    84170        return '\[('.$tagregexp.')\b(.*?)(?:(\/))?\](?:(.+?)\[\/\1\])?';
    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;
    89185
     
    99195        }
    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();
    104212        $pattern = '/(\w+)\s*=\s*"([^"]*)"(?:\s|$)|(\w+)\s*=\s*\'([^\']*)\'(?:\s|$)|(\w+)\s*=\s*([^\s\'"]+)(?:\s|$)|"([^"]*)"(?:\s|$)|(\S+)(?:\s|$)/';
     
    122230        return $atts;
    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;
    127251        $out = array();
     
    134258        return $out;
    135259}
    136260
    137 /*
    138  * stip all the shortcodes from a post's content
    139  * returns the content without shortcodes
     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.
    140269 */
    141 function strip_shortcodes( $content ) {
    142        
     270function strip_shortcodes( $content ) {
    143271        global $shortcode_tags;
    144272
    145273        if (empty($shortcode_tags) || !is_array($shortcode_tags))
     
    148276        $pattern = get_shortcode_regex();
    149277
    150278        return preg_replace('/'.$pattern.'/s', '', $content);
    151        
    152279}
    153280
    154281add_filter('the_content', 'do_shortcode', 11); // AFTER wpautop()
    155282
    156 ?>
     283?>
     284 No newline at end of file