Docs: Improve documentation for add_shortcode() by:

* Removing inline examples already listed in the Code Reference
* Improving the summary and description to explain how tag conflicts are handled
* Supplement the docs for the `$func` parameter by describing the three arguments passed to a shortcode callback.

Props grapplerulrich for the initial patch.
Fixes #37222.

Built from https://develop.svn.wordpress.org/trunk@41281


git-svn-id: http://core.svn.wordpress.org/trunk@41121 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2017-08-20 19:44:42 +00:00
parent abf8e91521
commit 33997cc66c
2 changed files with 11 additions and 37 deletions

View File

@ -42,49 +42,23 @@
$shortcode_tags = array(); $shortcode_tags = array();
/** /**
* Add hook for shortcode tag. * Adds a new shortcode.
* *
* There can only be one hook for each shortcode. Which means that if another * Care should be taken, either through prefixing or other means,to ensure
* plugin has a similar shortcode, it will override yours or yours will override * that the shortcode tag being added is unique and will not conflict with
* theirs depending on which order the plugins are included and/or ran. * other, already-added shortcode tags. In the event of a duplicated tag, the
* * tag loaded last will take precedence.
* Simplest example of a shortcode tag using the API:
*
* // [footag foo="bar"]
* function footag_func( $atts ) {
* return "foo = {
* $atts[foo]
* }";
* }
* add_shortcode( 'footag', 'footag_func' );
*
* Example with nice attribute defaults:
*
* // [bartag foo="bar"]
* function bartag_func( $atts ) {
* $args = shortcode_atts( array(
* 'foo' => 'no foo',
* 'baz' => 'default baz',
* ), $atts );
*
* return "foo = {$args['foo']}";
* }
* add_shortcode( 'bartag', 'bartag_func' );
*
* Example with enclosed content:
*
* // [baztag]content[/baztag]
* function baztag_func( $atts, $content = '' ) {
* return "content = $content";
* }
* add_shortcode( 'baztag', 'baztag_func' );
* *
* @since 2.5.0 * @since 2.5.0
* *
* @global array $shortcode_tags * @global array $shortcode_tags
* *
* @param string $tag Shortcode tag to be searched in post content. * @param string $tag Shortcode tag to be searched in post content.
* @param callable $func Hook to run when shortcode is found. * @param callable $func The callback function to run when the shortcode is found.
* Every shortcode callback is passed three parameters by default,
* including an array of attributes (`$atts`), the content
* the shortcode was found in (`$content`), and finally
* the shortcode tag itself (`$shortcode_tag`), in that order.
*/ */
function add_shortcode($tag, $func) { function add_shortcode($tag, $func) {
global $shortcode_tags; global $shortcode_tags;

View File

@ -4,7 +4,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '4.9-alpha-41280'; $wp_version = '4.9-alpha-41281';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.