shortcodes in-depth
TRANSCRIPT
Shortcodes In-Depth
Micah Wood @wpscholarhttps://wpscholar.com/wcn2016
What is a shortcode?
Text
A text shortcut
A text shortcut dynamically replaced
A text shortcut dynamically replaced
with content
A text shortcut dynamically replaced
with content on render.
Built-In WordPress Shortcodes• [embed] – Allows you to embed various types of content into your posts
and pages.
• [caption] – Allows you to wrap captions around content (like images).
• [gallery] – Allows you to add one or more image galleries.
• [audio] – Allows you to embed audio files within an HTML5 audio player.
• [video] – Allows you to embed video files within an HTML 5 video player.
Shortcode Syntax
Basic Shortcode[shortcode]
Shortcode with Attributes[shortcode attribute=“value”]
Shortcode with Content[shortcode]content[/shortcode]
Compound Shortcode[shortcode attribute=“value”]content[/shortcode]
Escaped Shortcode[[shortcode]]
When should I use shortcodes?
When Embedding Objects or iFrames
When Code is Required
Complex HTML Markup
Shortcode Example Use Cases• Inject AdWords conversion tracking code on a page
• Insert a Google Map
• Insert a widget into the content of a page
• Create a footnote
• Display a random image
Where can I use shortcodes?
Content Editor[shortcode]
Theme Templates<?php echo do_shortcode(‘[shortcode]’); ?>
Excerpts<?php add_filter( 'the_excerpt', 'do_shortcode'); ?>
Text Widgets<?php add_filter( ‘widget_text', 'do_shortcode'); ?>
Comments<?php add_filter( ‘comment_text', 'do_shortcode'); ?>
Anywhere They Are Enabled<?php echo do_shortcode($content); ?>
How do I create a shortcode?
Register the Shortcode<?php add_shortcode(‘shortcode’, ‘callback’); ?>
Create the Callback<?php
function callback( $atts = [], $content = null, $tag = '' ) { return $content;
}
add_shortcode( 'shortcode', 'callback' );
?>
Setup Attributes<?php
function callback( $atts = [], $content = null, $tag = '' ) { $defaults = array( 'id' => 0 ); $atts = shortcode_atts( $defaults, $atts, $tag );
return $content;
}
add_shortcode( 'shortcode', 'callback' );
?>
Ensure Attributes are Lowercase<?php
function callback( $atts = [], $content = null, $tag = '' ) { $defaults = array( 'id' => 0 ); $atts = array_change_key_case( $atts, CASE_LOWER ); $atts = shortcode_atts( $defaults, $atts, $tag );
return $content;
}
add_shortcode( 'shortcode', 'callback' );
?>
Do Custom Stuff<?php
function callback( $atts = [], $content = null, $tag = '' ) {
$defaults = array( 'id' => 0 ); $atts = array_change_key_case( $atts, CASE_LOWER ); $atts = shortcode_atts( $defaults, $atts, $tag );
if ( $atts['id'] ) {
$post = get_post( $atts['id'] ); if ( $post ) {
$content = '<a href="' . esc_url( get_permalink( $post->ID ) ) . '">' . $content . '</a>'; }
}
return $content; }
add_shortcode( 'shortcode', 'callback' );
?>
Allow for Nested Shortcodes<?php
function callback( $atts = [], $content = null, $tag = '' ) {
$defaults = array( 'id' => 0 ); $atts = array_change_key_case( $atts, CASE_LOWER ); $atts = shortcode_atts( $defaults, $atts, $tag );
if ( $atts['id'] ) {
$post = get_post( $atts['id'] ); if ( $post ) {
$content = '<a href="' . esc_url( get_permalink( $post->ID ) ) . '">' . $content . '</a>'; }
}
$content = do_shortcode( $content );
return $content; }
add_shortcode( 'shortcode', 'callback' );
?>
Why doesn’t my shortcode work?
Return, Don’t Echo
Shortcode Names Can’t Use Reserved Characters:
& / < > [ ] =
Shortcode Nesting is up to the Author
Can’t Nest Shortcodes with the Same Name
Can’t Mix Enclosing and Non-Enclosing Shortcodes with the Same Name
Best Practices
Provide Detailed Documentation
Display Helpful Messages
Prefix Shortcode Names
Sanitize Input, Escape Output
Avoid Side Effects
Shortcode API
add_shortcode()Registers a new shortcode
do_shortcode()Processes all shortcodes in the content
remove_shortcode()Disables a specific shortcode
remove_all_shortcodes()Disables all shortcodes
has_shortcode()Checks if a shortcode exists in the content
shortcode_exists()Checks if a specific shortcode has been registered
shortcode_atts()Combines default and provided shortcode attributes
Advanced Topics
Shortcodes in Plugins vs. Themes
What is Wrong with This? <?php echo do_shortcode(‘[shortcode]’); ?>
What is Wrong with This? <?php shortcode_callback( $atts, $content ); ?>
The Traditional Approach<?php if( function_exists( 'shortcode_callback' ) ) { shortcode_callback( $atts, $content );} ?>
The Modern Approach<?php do_action( 'shortcode', $atts, $content ); ?>
Implementing the Modern Approach<?php
add_shortcode('shortcode', 'shortcode_callback');
function shortcode_render( $atts = array(), $content = '' ) { echo shortcode_callback( $atts, $content );}
add_action( 'shortcode', 'shortcode_render', 10, 2 );
?>
Shortcode Resources• Plugin Handbook - Shortcodes
• WordPress Codex – Shortcodes
• WordPress Codex – Shortcode API
• Smashing Magazine – WordPress Shortcodes: A Complete Guide
• Generate WP – Shortcode Generator
• Shortcake Plugin (Shortcode UI)
• Digging into WordPress – Call a Widget with a Shortcode
Questions?
Shortcodes In-Depth
Micah Wood @wpscholarhttps://wpscholar.com/wcn2016