Using Shortcodes

Creating and Using Shortcodes in GeniXCMS

---

Shortcodes are a powerful feature in GeniXCMS version 2.0.0 that allow you to create dynamic, parameterized content within posts and pages. Unlike plain HTML, shortcodes are processed on the server at render time, making them ideal for injecting complex UI components like Table of Contents, Product Sliders, or Recent Posts.

This guide explains how to programmatically create and use shortcodes in your Modules and Themes.

---

🏗️ Basic Shortcode Architecture

A shortcode is a tag wrapped in square brackets, such as [my_tag key="value"]. To implement a shortcode in GeniXCMS, you need two things:

1. A Callback Function: Logic that generates the HTML for the shortcode.
2. A Hook Connection: Attaching your logic to the post_content_filter filter.

---

🛠️ Step 1: Create a Callback Function

In your module's index.php or theme's functions.php:

function my_module_render_shortcode($content) {
    // We use the Shortcode::parse library class
    return Shortcode::parse('hello', $content, function($attrs, $original) {
        // Step 1: Set defaults
        $name = $attrs['name'] ?? 'World';
        $color = $attrs['color'] ?? 'primary';

        // Step 2: Return the HTML to replace the [hello ...] string
        return "<span class=\"badge bg-{$color}\">Hello, {$name}!</span>";
    });
}

---

🏹 Step 2: Connect via Hooks

To make your shortcode work globally on all post/page content, attach your function to the post_content_filter hook.

// Register the filter during module/theme init
Hooks::attach('post_content_filter', 'my_module_render_shortcode');

---

🧪 Advanced Example: Fetching Content

Imagine a shortcode [user_info id="123"] that fetches a user's name:

$content = Shortcode::parse('user_info', $content, function($attrs) {
    $uid = (int)($attrs['id'] ?? 0);
    $user = User::fetch(['id' => $uid]);

    if (empty($user)) return "<em>User not found</em>";

    return "<strong>" . $user[0]->username . "</strong>";
});

---

🎛️ Implementation Table (Best Practices)

Action	Best Practice	Rationale
Parsing	Use Shortcode::parse	It is built-in, optimized, and supports complex attribute patterns.
Attributes	Always set defaults	Prevents undefined index notices and ensures consistent UI.
Output	Escape user data	Use htmlspecialchars() on any user-provided attribute used in HTML.
Sanitization	Avoid HTML tags	Shortcodes are for dynamic content; keep the raw tag clean of HTML.

---

🔒 Handling Aggressive Sanitizers

GeniXCMS uses HTML Purifier to clean post content on save. If you use custom HTML attributes like data-color="red", they might be stripped out by the security filter.

---

📝 Checklists for Developers

• [ ] Does your shortcode tag have a unique name?
• [ ] Have you attached your logic to post_content_filter?
• [ ] Are you returning the content (not echoing)?
• [ ] Have you documented the available attributes for your users?

---

See Also

• Shortcode Class API — Technical details of the Shortcode::parse method.
• Hooks API — Documentation for filters and actions.
• Creating Modules — Comprehensive guide on module development.