Shortcode Parser & Attribute Extraction Class
The Shortcode class (introduced in GeniXCMS 2.0.0) provides a standardized, high-performance engine for parsing dynamic tags and extracting their attributes within a text block. It is specifically designed to bypass aggressive backend sanitizers (like HTML Purifier) by embedding layout properties directly within a bracketed string (e.g., [toc title="My List" float="right"]).
⚡ Core Operational Concepts
Shortcodes are a powerful way to inject dynamic content or complex UI components into posts, pages, or any text field.
🛡️ Why Use Shortcodes?
- Immutability: Unlike HTML
data- attributes, content inside [...] is treated as simple text by sanitizers, meaning your attributes (lebar, tinggi, title) won't be stripped.
- Flexibility: Supports multiple attribute formats (quoted, unquoted, single-quote).
- Extensibility: Allows modules to register their own tags easily.
🏗️ Registering and Parsing Shortcodes
Shortcode::parse($tag, $content, $callback)
Scans the provided content for a specific tag and executes a callback for every match found.
// In your module or hook callback
$content = Shortcode::parse('my_tag', $content, function($attrs, $original) {
// $attrs is an associative array of key="value" pairs
$name = $attrs['name'] ?? 'Stranger';
return "Hello, <strong>{$name}</strong>!";
});
Shortcode::parseAttributes($attrStr)
A utility method to convert a raw attribute string (e.g., id="123" color='red' width=100%) into a clean associative array.
🧪 Implementation Workflow
| Method |
Role |
Input |
Output |
parse($tag, $content, $fn) |
The Engine |
Tag name, raw content, and rendering logic. |
Processed string with rendered shortcodes. |
parseAttributes($str) |
The Parser |
A raw string of attributes. |
An associative key => value array. |
🏹 Native Shortcodes in GxEditor
The GeniXCMS official block editor utilizes this class for several high-impact components:
[toc ...]: Table of Contents with dynamic heading detection.[image ...]: Robust image layout with alignment and styling attributes.[post id="X"]: Previews a single post by its ID.[recent_posts count="5"]: Lists the most recent content.
🛠️ Developer Best Practices
- Defaults: Always provide fallback values for your attributes (e.g.,
$count = $attrs['count'] ?? 5;).
- HTML Safety: When returning HTML from a shortcode callback, ensure you escape any user-provided attributes if necessary using
htmlspecialchars().
- Global Filters: It is recommended to attach your shortcode parsing logic to the
post_content_filter hook to ensure it runs during frontend rendering.
lightbulbTipPerformance: Shortcode::parse uses a pre-check with strpos before executing regex, making it extremely efficient for large pieces of content that may not contain the tag.
See Also
