Shortcodes In-Depth

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.

WordPress.com / JetPackhttps://en.support.wordpress.com/shortcodes/

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