Contents
Introduction
Custom shortcodes are one of WordPress’s most powerful features. They enable theme and plugin developers to let end users inject dynamic or complex content into posts and pages with a simple tag. In this article, you will learn step-by-step how to create, register, and manage custom shortcodes in WordPress, covering everything from basic syntax to advanced best practices.
Why Use Custom Shortcodes
- Reusability: Write code once and deploy it via a simple tag.
- Separation of Concerns: Keep markup and PHP logic out of post content.
- Flexibility: Accept attributes to customize output per usage.
- Maintainability: Easily update functionality in one place.
Basic Anatomy of a Shortcode
- Tag Name: The string users type, e.g.
[greeting]. - Callback Function: PHP function that builds output.
- Attributes: Optional or required parameters passed inside the tag.
- Enclosing Content: For wrap-around shortcodes that surround content.
1. Registering a Shortcode
Use add_shortcode() to hook your callback to a tag:
ltphp
function my_greeting_shortcode( atts ) {
return ltpgtHello, visitor!lt/pgt
}
add_shortcode( greeting, my_greeting_shortcode )
Now, [greeting] in a post will render “Hello, visitor!”.
2. Handling Attributes
You’ll often need custom parameters. Use shortcode_atts() for defaults:
ltphp
function my_greeting_shortcode( atts ) {
atts = shortcode_atts( array(
name =gt Guest,
style =gt italic
), atts, greeting )
return sprintf(
ltp style=quotfont-style:%1squotgtHello, %2s!lt/pgt,
esc_attr( atts[style] ),
esc_html( atts[name] )
)
}
add_shortcode( greeting, my_greeting_shortcode )
Usage: [greeting name=Alice style=bold]. Default values ensure robust fallback behavior.
Enclosing (Pair) Shortcodes
Sometimes you want to wrap content. Structure your callback to accept content:
ltphp
function highlight_shortcode( atts, content = null ) {
return ltdiv style=quotbackground:#ffffe0padding:10pxborder-left:3px solid #ff0quotgtltstronggtNote:lt/stronggt .
do_shortcode( content ) .
lt/divgt
}
add_shortcode( highlight, highlight_shortcode )
Use: [highlight]Important text here[/highlight].
Advanced Techniques
Nested Shortcodes
If your content contains other shortcodes, always wrap content in do_shortcode() to process nested tags.
Output Buffering
For complex HTML, you can use PHP’s output buffering:
ltphp
function gallery_slider_shortcode( atts ) {
atts = shortcode_atts( array(
ids =gt
), atts, gallery_slider )
ids = explode( ,, atts[ids] )
ob_start()
gt
ltdiv class=my-slider style=display:flexgap:10pxgt
ltphp foreach ( ids as id ) :
img = wp_get_attachment_image_src( intval(id), medium )
gt
ltimg src=ltphp echo esc_url(img[0]) gt alt= style=max-width:100pxborder:1px solid #cccpadding:2px /gt
ltphp endforeach gt
lt/divgt
ltphp
return ob_get_clean()
}
add_shortcode( gallery_slider, gallery_slider_shortcode )
Using Classes and OOP
For large projects, encapsulate shortcodes in a class:
ltphp
class My_Shortcodes {
public function __construct() {
add_shortcode( promo_box, array( this, promo_box ) )
}
public function promo_box( atts, content = null ) {
atts = shortcode_atts( array( color =gt #dff0d8 ), atts, promo_box )
return ltdiv style=quotbackground: . esc_attr(atts[color]) . padding:15pxborder-radius:4pxquotgt
. do_shortcode(content) .
lt/divgt
}
}
new My_Shortcodes()
Security and Best Practices
- Always sanitize and escape input/output: use
esc_attr(),esc_html(),wp_kses_post(). - Avoid
eval()and other risky operations. - Validate attribute types (ints, URLs) before use.
- If outputting HTML, whitelist tags with
wp_kses()when necessary.
Internationalization (i18n)
Wrap user-facing text with translation functions:
ltphp
function greeting_i18n_shortcode( atts ) {
attrs = shortcode_atts( array( name =gt __( Guest, my-text-domain ) ), atts, greeting_i18n )
return sprintf(
ltpgt%s, %s!lt/pgt,
esc_html__( Hello, my-text-domain ),
esc_html( attrs[name] )
)
}
add_shortcode( greeting_i18n, greeting_i18n_shortcode )
Performance Considerations
- Cache expensive queries inside shortcodes with
wp_cache_set()/wp_cache_get(). - Minimize DOM elements and inline styles enqueue external styles/scripts via
wp_enqueue_scripts. - Use transient API for third-party API calls.
Shortcode Examples Gallery
| Shortcode | Description |
|---|---|
| [greeting name=Alice] | Displays a personalized greeting. |
| [highlight]…[/highlight] | Wraps content in a highlighted box. |
| [gallery_slider ids=1,2,3] | Renders a simple thumbnail slider. |
| [promo_box color=#ffdddd]Your Text[/promo_box] | Displays content in a promotional box. |
Debugging Troubleshooting
- Enable
WP_DEBUGinwp-config.phpto catch PHP errors. - Use
var_dump()orerror_log()inside callbacks for troubleshooting. - Check for shortcode conflicts: ensure your tag name is unique.
- Test in the Classic Editor and Block Editor (Gutenberg) to confirm compatibility.
Resources
- add_shortcode() – WordPress Developer Resources
- Shortcode API Explained – WordPress Developer Resources
- Shortcode API – WordPress Codex
Conclusion
Custom shortcodes empower you to provide rich, dynamic functionality to end users in a simple, user-friendly way. By following best practices—sanitizing input, caching heavy operations, and structuring code cleanly—you can create maintainable, high-performance shortcodes for any WordPress project.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |