With everything set up I'm choosing to practice making shortcodes because I'm not familiar with them at all. First though, I'm going to take some notes on this: http://codex.wordpress.org/Shortcode_API
Basically a shortcode is a placeholder that you put in posts that gets replaced with the code when displayed. It's kinda like when you use :ninja: in the chatbox at wj to get a ninja smiley. Shortcodes can also have attributes (color, size, id, etc.).
Then to write a shortcode, in your functions.php, you just have to write a function that returns the html/text you need and use add_shortcode() for that function: http://codex.wordpress.org/Function_Reference/add_shortcode
There are three parameters included in the shortcode callback:
Besides using self-closing shortcode, you can enclose shortcodes by using this format in posts: [shortcode]content[shortcode]. Doing so will not send the second (content) parameter to the handler so you'd have to set the handler's default value:
- $atts, is an optional array of attributes.
- $content, is the content of the shortcode (obviously)
- $tag, is a tag for the shortcode, used for shared callback functions.
The shortcode api will replace any shortcodes [thatlooklikethis] and parse all the attributes and content. Content will only be placed in the post body if it's returned and not echoed. A shortcode handler would get put into the body instead of the shortcode already programmed.
So say you have something like: [scode dont="touch" me="there"]
The $atts would be: array( 'dont' => 'touch', 'me' => 'there' )
$atts[0] holds a string that was used to match the shortcode regex if (and only if) it's different from the callback name.
shortcode_atts (resembles wp_parse_args) is used to set a default for missing values and get rid of any attributes that the shortcode doesn't understand: http://codex.wordpress.org/Function_Reference/shortcode_atts
This would get placed inside of an add_shortcode handler function like this:
Here, extract (http://www.php.net/extract) pulls the needed values from the array and will handle any collisions after shortcode_atts() strips out all the non-included keys.
This tip is important regarding naming attributes:
So say you have something like: [scode dont="touch" me="there"]
The $atts would be: array( 'dont' => 'touch', 'me' => 'there' )
$atts[0] holds a string that was used to match the shortcode regex if (and only if) it's different from the callback name.
shortcode_atts (resembles wp_parse_args) is used to set a default for missing values and get rid of any attributes that the shortcode doesn't understand: http://codex.wordpress.org/Function_Reference/shortcode_atts
This would get placed inside of an add_shortcode handler function like this:
function my_shortcode_handler( $atts, $content = null ) {
extract( shortcode_atts( array(
'attr_1' => 'attribute 1 default',
'attr_2' => 'attribute 2 default',
// ...etc
), $atts ) );
}Here, extract (http://www.php.net/extract) pulls the needed values from the array and will handle any collisions after shortcode_atts() strips out all the non-included keys.
This tip is important regarding naming attributes:
$atts values are lower-cased during shortcode_atts( array( 'attr_1' => 'attr_1 default', // ...etc ), $atts ) processing, so you might want to just use lower-case.Shortcodes get parsed after wpautop and wptexturize formatting is applied, meaning it won't have the proper html (p and br) tags added or curly quotes applied. To format the shortcode, just call wpautop() and wptexturize when you return the output from your handler. If there's a lot of html in the shortcode you can use ob_start() to capture the output and convert it to a string:
ob_start();
?> <HTML> <here> ... <?PHP
$output_string = ob_get_contents();
ob_end_clean();Besides using self-closing shortcode, you can enclose shortcodes by using this format in posts: [shortcode]content[shortcode]. Doing so will not send the second (content) parameter to the handler so you'd have to set the handler's default value:
function my_shortcode_handler( $atts, $content = null )Don't know what kind of closing a shortcode has? You can use is_null($content) to figure that out. Other html can be embed in $content since it's not encoded or escaped but you can add another shortcode unless you output it using do_shortcode(): http://codex.wordpress.org/Function_Reference/do_shortcode
You can mix forms of enclosing or non-enclosing shortcodes:
[sc title="steez" /] this aint [sc] working [/sc]This would output: this aint [sc] working
Enclosing shortcodes work the same way as self-enclosing. An example:
function caption_shortcode( $atts, $content = null ) {
extract( shortcode_atts( array(
'class' => 'caption',
), $atts ) );
return '<span class="' . esc_attr($class) . '">' . $content . '</span>';
}Input: [caption class="headline"]My Caption[/caption]
Output: <span class="headline">My Caption</span>
You cannot use square brackets in attributes. So [sc attribute="[this will not work]"].
There's a few other things to note about shortcodes but I think I've summarized the important stuff.
No comments:
Post a Comment