Creating Custom Shortcodes in PolyCMS

What Are Shortcodes?

Shortcodes are bracket-syntax tags that get replaced with dynamic HTML when content is rendered on the frontend. They allow content editors to embed complex components (galleries, accordions, call-to-action blocks) without writing HTML.

Registering a Custom Shortcode

Register shortcodes in your plugin's main file or in a theme's functions.php:

polycms_add_shortcode('my_cta', function($atts, $content = '') {
    $defaults = [
        'text'  => 'Learn More',
        'url'   => '#',
        'color' => 'primary',
    ];
    $atts = shortcode_atts($defaults, $atts);

    return '<div class="cta-block cta-' . esc_attr($atts['color']) . '">'
         . '<a href="' . esc_url($atts['url']) . '">' . esc_html($atts['text']) . '</a>'
         . '</div>';
});

Usage in Content

[my_cta text="Get Started" url="/pricing" color="green"]

Shortcode Attributes

Attributes are key-value pairs passed inside the shortcode tag:

[shortcode_name key1="value1" key2="value2"]

Use shortcode_atts() to merge user-provided attributes with defaults, ensuring missing attributes fall back to safe default values.

Enclosing Shortcodes

Shortcodes can wrap content between opening and closing tags:

polycms_add_shortcode('highlight', function($atts, $content = '') {
    $defaults = ['color' => 'yellow'];
    $atts = shortcode_atts($defaults, $atts);

    return '<span class="highlight" style="background:' . esc_attr($atts['color']) . ';">'
         . do_shortcode($content) // Process nested shortcodes
         . '</span>';
});

Usage

[highlight color="yellow"]This text is highlighted.[/highlight]

Example: Accordion Shortcode

polycms_add_shortcode('accordion', function($atts, $content = '') {
    $defaults = [
        'title' => 'Click to expand',
        'open'  => 'false',
    ];
    $atts = shortcode_atts($defaults, $atts);

    $id = 'accordion-' . uniqid();
    $openClass = $atts['open'] === 'true' ? 'open' : '';

    return '<div class="polycms-accordion ' . $openClass . '" id="' . $id . '">'
         . '<div class="accordion-header" onclick="this.parentElement.classList.toggle(\'open\')">'
         . esc_html($atts['title'])
         . '</div>'
         . '<div class="accordion-body">' . do_shortcode($content) . '</div>'
         . '</div>';
});

Nested Shortcodes

Call do_shortcode($content) inside your shortcode handler to process any shortcodes nested within the content block. This enables composable shortcode patterns:

[accordion title="FAQ Item 1"]
  [highlight color="green"]Important:[/highlight] This is the answer.
[/accordion]

Best Practices

• Always use shortcode_atts() to define defaults and sanitize input.
• Escape output with esc_attr(), esc_html(), and esc_url() to prevent XSS.
• Use do_shortcode($content) for enclosing shortcodes to enable nesting.
• Prefix shortcode names to avoid conflicts with other plugins (e.g., myplugin_gallery).
• Register shortcodes during plugin initialization, not inside conditional blocks.

Need Help?

Building custom shortcodes and need guidance? Leave a comment on our CodeCanyon page. We provide completely free support for all PolyCMS customers — including code examples and debugging assistance.

Related Documentation

• Widgets & Sidebars — Built-in shortcodes and widget management.
• Building a Custom Plugin — Register shortcodes within plugin architecture.
• Hooks & Filters Reference — Hook into shortcode processing lifecycle.