Zen Shortcodes Pro: Official User Manual & Documentation

The Ultimate Native Visual Shortcode Builder for Joomla 6 & PHP 8.1+

Introduction

Zen Shortcodes Pro bridges the gap between simple text editing and complex page building. It provides 16 FREE shortcodes available immediately from the editor, 14 configurable Magic Templates, and 8 advanced PRO elements — all insertable through a visual modal without writing a single line of HTML. Built natively for Joomla 6, it replaces PHP-injection plugins like Sourcerer with a secure, ACL-aware architecture: shortcodes are stored in the database, rendered cleanly by the content plugin, and configured visually in both the backend and the article editor.

Part 1: Installation & Activation

1.1. Installing the Package

1. Download the pkg_zenshortcodes_pro.zip file from JED or from zen.etegan.eu.

2. Navigate to Extensions → Manage → Install in your Joomla Administrator panel.

3. Upload the archive. The system automatically installs three extensions: the admin component com_zenshortcodes, the content plugin plg_content_zenshortcodes, and the editor button plugin plg_editors-xtd_zenshortcodes.

4. Navigate to Extensions → Plugins and ensure both plugins are enabled (green status): Content - Zen Shortcodes and Editors Extended Button - Zen Shortcodes.

1.2. Verification

Navigate to Components → Zen Shortcodes. You should see the dashboard with zero shortcodes. If you see a missing table error, run sql/install.mysql.utf8.sql manually from phpMyAdmin on your Joomla database.

1.3. Uninstalling

Go to Extensions → Manage → Manage, search for pkg_zenshortcodes, select it and click Uninstall. All three extensions and the database table are removed automatically.

Part 2: Using Shortcodes in Articles

2.1. The Editor Button

When editing any article, below the TinyMCE or JCE toolbar you will see the Zen Shortcodes button. Clicking it opens the Visual Builder Modal.

2.2. Navigating the Modal

The left panel displays five categories: Favorites, Media, UI Elements, Design, and Custom Elements. Clicking a category shows the available shortcode cards. A search bar at the top filters across all categories simultaneously.

2.3. Configuring and Inserting

Click any shortcode card to open its configuration form in the right panel. Fill in the fields, select images via the native Media Manager (Browse button), choose icons from the visual dropdown. The Shortcode Preview at the bottom updates in real time. Click Insert Shortcode to place the code at the cursor position in the editor.

2.4. Manual Insertion

Shortcodes can also be typed directly in the article. The general format is:

[zen_TAG attribute1="value1" attribute2="value2"]

Or for shortcodes with inner content:

[zen_TAG attribute="value"]Inner content[/zen_TAG]

2.5. Visibility Conditions

Every shortcode accepts optional visibility attributes, processed server-side in PHP:

• visible — all / mobile / tablet / desktop
• group — all / public / registered / author / manager / administrator
• show_from / show_until — date in YYYY-MM-DD format
• lang — Joomla language tag, e.g. ro-RO, en-GB

Part 3: FREE Shortcodes — Complete Reference

All 16 FREE shortcodes are accessible directly from the modal without any backend configuration.

3.1. Media Category 🎬

[zen_youtube] — YouTube Video
Embeds a responsive 16:9 YouTube video.
[zen_youtube url="https://www.youtube.com/watch?v=ID"]
Attribute: url — full video URL (required). Also works with embed URLs.

[zen_vimeo] — Vimeo Video
Embeds a Vimeo video with a responsive player.
[zen_vimeo url="https://vimeo.com/123456789"]
Attribute: url — full Vimeo video URL (required).

[zen_map] — Google Maps
Displays a Google Maps embed at a specified address.
[zen_map address="Craiova, Romania" zoom="15"]
Attributes: address (required), zoom — level 1–21 (default: 15).

[zen_gallery] — Photo Gallery
Displays a responsive CSS grid photo gallery from all images in a Media Manager folder, with a vanilla JS lightbox (no external libraries), arrow-key navigation and Escape to close.
[zen_gallery folder="images/gallery" cols="3" lightbox="1" limit="12"]
Attributes: folder — path relative to Joomla root (required); cols — 2, 3, or 4 (default: 3); lightbox — 1/0 (default: 1); limit — maximum images, 0 = all (default: 0). Filters automatically by image extensions: jpg, jpeg, png, gif, webp.

3.2. UI Elements Category 🎨

[zen_alert] — Bootstrap 5 Alert
Generates a styled Bootstrap 5 alert box. Inner content accepts plain HTML.
[zen_alert type="success"]Your message here.[/zen_alert]
Attribute: type — info / success / warning / danger / primary / secondary / light / dark (default: info).

[zen_button] — Link Button
Generates a styled Bootstrap link button.
[zen_button link="https://example.com" type="primary" target="_blank"]Click here[/zen_button]
Attributes: link (default: #); type — Bootstrap color variant; target — _blank for new tab.

[zen_tooltip] — Bootstrap Tooltip
Displays a Bootstrap tooltip on hover over the marked text.
[zen_tooltip text="Explanation" position="top"]Hover me[/zen_tooltip]
Attributes: text (required); position — top / bottom / left / right (default: top).

[zen_highlight] — Text Highlight
Applies background and text colours to a fragment.
[zen_highlight bg="#ffff00" color="#000000"]Important text[/zen_highlight]
Attributes: bg — background CSS colour (default: #ffff00); color — text CSS colour (default: #000000).

[zen_tabs] and [zen_tab] — Bootstrap 5 Tabs
Creates a native Bootstrap 5 tab set. Each [zen_tab] defines a panel with full HTML content or other shortcodes. IDs are generated with uniqid() — multiple tab sets on the same page work independently.
[zen_tabs]
  [zen_tab label="Tab 1" active="1"]Content 1[/zen_tab]
  [zen_tab label="Tab 2" icon="fa-star"]Content 2[/zen_tab]
[/zen_tabs]
Attributes per [zen_tab]: label (required); active — 1 = active by default; icon — optional FA class.

[zen_accordion] and [zen_item] — Bootstrap 5 Accordion
Displays content in Bootstrap 5 collapsible panels. Ideal for FAQ sections.
[zen_accordion multiple="0"]
  [zen_item title="Question 1" open="1"]Answer 1[/zen_item]
  [zen_item title="Question 2"]Answer 2[/zen_item]
[/zen_accordion]
Attributes: multiple — 0 = one panel open at a time, 1 = multiple simultaneously (default: 0); title (required); open — 1 = open by default.

3.3. Design Category ✨

[zen_icon] — FontAwesome Icon
Displays a FontAwesome 6 Free icon. In the modal, icons are selected visually from a list with preview.
[zen_icon name="fa-star" type="solid" color="#f59e0b" size="2x"]
Attributes: name — FA class without fa- prefix; type — solid / regular / brands; color — CSS colour; size — 1x / 2x / 3x / lg / xl.

[zen_social] — Social Network Link
Displays a social network link with a FontAwesome Brands icon. Always use the full URL with https://.
[zen_social network="linkedin" link="https://linkedin.com/in/profile" color="#0077b5" size="2x"]
Attributes: network — facebook / x-twitter / instagram / linkedin / tiktok / youtube (and others); link; color; size.

[zen_columns] and [zen_col] — Multi-Column CSS Grid
Creates a responsive CSS Grid layout. Each [zen_col] is an independent column with full HTML content or nested shortcodes.
[zen_columns cols="3" gap="20px" stack="md"]
  [zen_col]Column 1[/zen_col]
  [zen_col]Column 2[/zen_col]
  [zen_col]Column 3[/zen_col]
[/zen_columns]
Attributes: cols — 2, 3, 4 (default: 2); gap (default: 20px); stack — sm (576px) / md (768px) / lg (1024px).

[zen_panel] — Styled Box Container
Displays content inside a container with configurable background, border, shadow and alignment.
[zen_panel bg="#e8f4fd" border="#0d6efd" border_width="2px" radius="12px" shadow="1" padding="25px"]Content[/zen_panel]
Attributes: bg (default: #f8f9fa); border — border colour, omit for no border; border_width (default: 1px); radius (default: 8px); shadow — 1/0 (default: 0); padding (default: 20px); align — left / center / right.

[zen_spacer] — Vertical Space
Adds configurable vertical whitespace between elements.
[zen_spacer height="40px"]
Attribute: height — any CSS unit (default: 20px).

[zen_divider] — Divider Line
Displays a styled horizontal rule.
[zen_divider type="dashed" color="#94a3b8" size="2px"]
Attributes: type — solid / dashed / dotted (default: solid); color (default: #dee2e6); size (default: 1px).

Part 4: PRO Advanced Shortcodes

Available in the content plugin — no backend configuration required. Insert directly using shortcode syntax or the Custom Elements section of the modal.

[zen_cta] — Call-to-Action Section
Visual section with title, subtitle and up to 2 CTA buttons.
[zen_cta title="Ready to start?" subtitle="Join our community." btn1_text="Try Free" btn1_link="https://..." btn2_text="Demo" btn2_link="https://..." bg="#0d6efd"]
Key attributes: title (required); subtitle; btn1_text / btn1_link; btn2_text / btn2_link; bg; text_color; align.

[zen_testimonial] — Testimonial Card
Testimonial with quote text, author, star rating and avatar. Avatar is optional — if omitted, the author's initials appear in a coloured circle.
[zen_testimonial author="John Smith" role="CEO" rating="5" avatar="images/john.jpg"]Quote text.[/zen_testimonial]
Key attributes: author (required); role; rating — 1–5 or 0 for none (default: 5); avatar; bg.

[zen_countdown] — Live Countdown Timer
A live countdown in JavaScript with days, hours, minutes and seconds. Multiple countdowns on the same page work independently.
[zen_countdown date="2026-12-31 23:59:59" label="Offer expires in:" expired_text="The offer has ended!"]
Attributes: date — YYYY-MM-DD HH:MM:SS (required); label; expired_text.

[zen_pricing] and [zen_plan] — Pricing Table
Pricing plan cards with feature lists, CTA button and featured plan highlighting. Lines with ~~text~~ render as struck-through (excluded) features.
[zen_pricing]
  [zen_plan name="Free" price="0" currency="EUR" btn_text="Download" btn_link="https://..."]
  Included feature
  ~~Excluded feature~~
  [/zen_plan]
  [zen_plan name="PRO" price="29" featured="1" btn_text="Buy PRO" btn_link="https://..."]
  All features
  [/zen_plan]
[/zen_pricing]
Key attributes per plan: name; price; currency / period; featured — 1 adds accent border and RECOMMENDED badge; btn_text / btn_link.

[zen_progress] and [zen_bar] — Animated Progress Bars
Progress bars animated on scroll via the Intersection Observer API — no jQuery or external libraries. Animation triggers only when the element enters the viewport.
[zen_progress]
  [zen_bar label="PHP" value="90" color="#777BB3"]
  [zen_bar label="Joomla" value="95" color="#F0741E"]
[/zen_progress]
Attributes per bar: label (required); value — 0–100 (required); color (default: #0d6efd); show_value — 1/0.

[zen_codeblock] — Syntax-Highlighted Code Block
Displays source code with Prism.js syntax highlighting, lazy-loaded from CDN. Supports line numbers and an optional header title.
[zen_codeblock lang="php" title="Example plugin" lines="1"]
  <?php defined('_JEXEC') or die;
[/zen_codeblock]
Attributes: lang — php / html / css / js / bash / json / xml (default: php); title; lines — 1/0 (default: 1).

[zen_article] — Inline Article Embed
Embeds a Joomla article's content inside another article. If the current user does not have view permission for the embedded article, nothing is rendered.
[zen_article id="42" display="intro" style="card" show_title="1"]
Attributes: id (required); display — title / intro / full (default: intro); style — inline / card / link; show_title — 1/0.

[zen_if] — Universal Conditional Wrapper
Displays any HTML or Zen shortcodes conditionally. All conditions are evaluated server-side in PHP — no client-side bypass possible.
[zen_if group="registered" visible="desktop" lang="en-GB"]
  Conditional content or other shortcodes
[/zen_if]
Attributes: group; visible; show_from / show_until; lang.

Part 5: The PRO Magic Templates — Backend Builder

5.1. Creating a Magic Template Shortcode

1. Go to Components → Zen Shortcodes → New.

2. Enter a Title and click one of the 14 buttons in the Magic Templates Library. The Tag field is auto-populated with a unique identifier.

3. The Template Configurator opens with color pickers, size sliders, and typography controls. The Live Preview updates in real time as you adjust values.

4. Fill in the Content Fields (the {{placeholder}} variables).

5. Click Inject HTML to generate the Output HTML, then Save & Close.

5.2. Iterative Templates — The Repeater Engine

Templates marked as iterative support adding elements beyond the base count. In the Template Configurator, click the âž• Add [Element] button to generate an additional slot:

• 3 Column Features (base: 3) — Add Feature: icon + title + text per new column
• Timeline (base: 3) — Add Interval: date + stage title + description per new milestone
• Statistics Counters (base: 3) — Add Stat: number + label per new counter
• Team Card (base: LinkedIn + X/Twitter) — Add Social URL: URL + icon per new social network
• Trust Badges (base: 3) — Add Logo: image URL per new partner logo
• Numbered Steps (base: 3) — Add Step: title + description per new step
• Tags / Chips (base: 4) — Add Chip: label per new tag

5.3. Multiple Shortcodes from the Same Template

You can create several shortcodes from the same Magic Template, each with different colors, content and number of elements. For example: two Timeline shortcodes with different accent colors for two different sections of your site. Each shortcode receives a unique tag (e.g. timeline_574, timeline_821) and is fully independent.

5.4. Inserting a Magic Template Shortcode in an Article

1. In the article editor, click the Zen Shortcodes button.

2. Go to the Custom Elements category in the left panel.

3. Select your shortcode. The right panel shows the configuration form with the actual value fields (not variable names).

4. For iterative shortcodes, use the Add Social URL / Add Feature etc. button to add extra elements beyond the base.

5. Click Insert Shortcode.

Part 6: Media Manager Integration & URL Guidelines

6.1. Selecting Images

Any image field in the modal shows a Browse button that opens Joomla's native Media Manager in a popup. Select any image or file and click Insert Selected. The path is automatically normalized to a clean relative format (e.g. images/photo.jpg) — no double subfolder paths.

6.2. URL Guidelines for Social Links and Buttons

Always enter the full URL including the protocol: https://linkedin.com/in/profile, not linkedin.com/in/profile. If you enter a URL without https://, the modal will auto-correct it on leaving the field (blur event). The content plugin also applies the same correction server-side at render time, so existing shortcodes saved without a protocol are fixed automatically on display.

6.3. Uploading Non-Image Files (PDF, DOC)

By default, Joomla restricts which file types can be uploaded to the Media Manager. To allow PDF or document uploads, go to System → Global Configuration → Media → Allowed Media Extensions and add the desired extension (e.g. pdf, docx). Note that .doc and .docx files may contain macros — assess the security risk before enabling them on public-facing sites.

Part 7: Presets & Export / Import

7.1. Saving a Preset

After configuring a shortcode in the modal, click the 💾 Preset button. Enter a name and the configuration is saved locally (browser localStorage). On the next visit, your preset appears in the Favorites category for one-click reuse across the entire site.

7.2. Export / Import JSON

In the backend shortcode edit form (Publishing Options section), the Export JSON and Import JSON buttons allow you to back up the full visual configuration (colors, sizes, content, iterative elements) and transfer it to another Joomla installation.

Part 8: Troubleshooting

8.1. Shortcode not rendering on the site

• Is the Content - Zen Shortcodes plugin enabled in Extensions → Plugins?
• Is the shortcode Status set to Published in Components → Zen Shortcodes?
• Does the tag in the article (e.g. [zen_timeline_574 ...]) exactly match the tag stored in the database?
• Shortcodes embedded inside bold or italic markup may be ignored — insert them in plain text.

8.2. Installation error: Table does not exist

• Run sql/install.mysql.utf8.sql manually from phpMyAdmin.
• Version 1.0.1+ includes sql/updates/mysql/1.0.1.sql, which runs automatically on each Joomla update.

8.3. Social link URLs broken (linkedin.com/... renders as a broken link)

• Always enter the full URL with https://.
• The modal auto-corrects on blur if the value contains a dot (external domain without protocol).
• The content plugin (v1.0.1+) applies the same correction server-side at render time.

8.4. Images appear with a doubled path (zen/zen/images/...)

• This occurs on Joomla installations in a subfolder (e.g. site.com/zen/).
• Fixed in v1.0.1+ — update the extension if you are running an older version.
• As a workaround, type the correct relative path directly in the image field: images/photo.jpg.

8.5. PDF or DOC files cannot be selected from Media Manager

• This is a native Joomla restriction, not a plugin limitation.
• Go to System → Global Configuration → Media → Allowed Media Extensions and add the required extension.

Zen Shortcodes Pro v1.0.1 | Built by ZenSuite Team | zen.etegan.eu