Helpers

AjaxCMS uses helpers to simplify inserting dynamic content and complex code. Helpers use a double-brace syntax: {{helper | param1 | param2 | ...}}. Parameters are separated by the pipe | character and processed in sequential order. Trailing parameters can be omitted if not needed.

Before a page is displayed, helpers are replaced with the appropriate HTML content.

Helper Syntax Rules

Displaying Helper Code in Documentation

Helper syntax inside code blocks (using backticks ` or triple backticks ```) is automatically protected from processing. This allows you to show helper examples in documentation without them being executed.

Example:

Use `{{a | home}}` to create a link to the home page.

The helper syntax above will display as-is in code blocks, not be processed.

Legacy method: Helpers with five or more sequential spaces are also skipped for backward compatibility, but this is no longer necessary with automatic code block protection.

HTML Attributes

All helpers (except {{insert}}) support attribute parameters using the => syntax. These inject HTML attributes into the generated element.

Format: attr=>value becomes attr="value" in the output HTML

Example:

{{a | documentation | class=>btn btn-primary | id=>nav-link}}

Becomes:

<a class="btn btn-primary" id="nav-link"
   onclick="loadPage('./pages/menus/01-Documentation/02-Helpers.md')">
   documentation
</a>

This works for any HTML attribute: class, id, style, data-*, aria-*, etc.

Markdown Support

Pages with .md extensions are processed through the marked Markdown parser (GitHub-flavored). See the GitHub Markdown Guide for syntax reference.

Available Helpers

Anchor (Link)

Syntax: {{a | page | link_text | alt_text}}

Creates an internal link that loads a page via AJAX without refreshing the browser. Uses partial matching to find pages, so you only need to specify enough of the filename to uniquely identify it.

Parameters:

Examples:

{{a | 01-Getting_Started.md}}
{{a | 01-Getting_Started.md | Get Started}}
{{a | 01-Getting_Started.md | Get Started | Getting Started Guide}}

With attributes:

{{a | home | Home Page | class=>nav-link active}}

Why use this instead of <a>? Regular HTML anchor tags (<a href="...">) cause full page reloads. The {{a}} helper creates links that load content via AJAX with smooth page transitions.

Image

Syntax: {{i | image | alt_text}}

Inserts an image from the images/ directory. Uses partial matching, so you only need enough of the filename to uniquely identify it.

Parameters:

Examples:

{{i | logo}}
{{i | logo | Company Logo}}
{{i | vacation/colorado.jpg | Mountain View}}

With CSS classes:

{{i | logo | Company Logo | class=>img-fluid rounded}}

Built-in CSS classes (defined in index.html):

Example with built-in classes:

{{i | photo | class=>medium left}}

Wildcard Support:

The image helper supports wildcards (*) to match multiple images. When a wildcard pattern is used, it automatically creates a responsive Bootstrap grid gallery.

Syntax: {{i | pattern | alt_text_or_per_row | per_row}}

Parameters:

Wildcard examples:

{{i | vacation/*}}                    ← Gallery with 3 images per row (default)
{{i | vacation/* | 4}}                ← Gallery with 4 images per row
{{i | vacation/* | Vacation Photos}}  ← Gallery with custom alt text, 3 per row
{{i | vacation/* | Vacation Photos | 5}} ← Gallery with alt text and 5 per row

How wildcards work:

Carousel (Slideshow)

Syntax: {{carousel:interval | image1:alt1:caption1 | image2:alt2:caption2 | ...}}

Creates a Bootstrap 5 carousel slideshow with multiple images. Supports unlimited slides.

Parameters:

Examples:

Basic carousel (3 slides, 5-second interval):

{{carousel:5000 | slide1.jpg | slide2.jpg | slide3.jpg}}

With alt text:

{{carousel:3000 | beach.jpg:Sunset at the beach | mountain.jpg:Mountain peak}}

With captions (HTML allowed):

{{carousel:4000 | product1.jpg:Product Image:<h3>New Arrival</h3><p>Check out our latest product</p> | product2.jpg:Product Image:<h3>Best Seller</h3><p>Our most popular item</p>}}

With CSS classes:

{{carousel:5000 | img1 | img2 | img3 | class=>carousel-fade}}

Wildcard Support:

Individual slide parameters can use wildcards (*) to match multiple images. Each matched image becomes a separate slide.

Wildcard examples:

{{carousel:5000 | vacation/*}}                               ← All images in vacation/ folder
{{carousel:3000 | vacation/*:Vacation Photo}}                ← All with same alt text
{{carousel:4000 | photos/2024-*::Trip to Europe}}            ← All with same caption
{{carousel:5000 | vacation/* | photos/city* | nature.jpg}}   ← Mix wildcards and specific images

How wildcards work:

Insert

Syntax: {{insert | page_name | allow_scripts}}

Embeds the content of another page at the helper location. The inserted page includes any layout.html that applies to it. Inserts can be nested (inserted pages can contain other inserts).

Parameters:

Examples:

{{insert | sidebar}}
{{insert | header}}
{{insert | footer | false}}

Use cases:

Note: The {{insert}} helper does NOT support attribute parameters. To add attributes, wrap it manually:

<div id="sidebar" class="col-md-4">
  {{insert | sidebar_content}}
</div>

File List

Syntax: {{filelist | directory_path}}

Generates a hierarchical menu from a directory and all its subdirectories. Uses standard HTML list format (<ul>, <li>).

Parameters:

Example:

{{filelist | ./pages/tutorials}}

Use cases:

Blog

Syntax: {{blog | directory | start | stop}}

Displays blog entries as expandable summaries. Entries load full content via AJAX when clicked. Blog files must follow a specific naming convention.

Parameters:

Blog file naming convention:

YYYY-MM-DD-Title.md
YYYY-MM-DD-Title.html
YYYY-MM-DD-n-Title.md  (n = optional number for multiple posts per day)

Examples:

2024-01-15-Hello_World.md
2024-01-15-1-Morning_Post.md
2024-01-15-2-Evening_Post.md

Usage:

{{blog | ./pages/blog}}
{{blog | ./pages/blog | 0 | 5}}    ← Show first 5 posts
{{blog | ./pages/blog | 5 | 10}}   ← Show posts 5-10 (pagination)

How it works:

Blog List

Syntax: {{bloglist | directory | start | stop}}

Displays a simple list of blog post titles with links. Similar to {{blog}} but shows only titles without excerpts or expansion.

Parameters:

Blog file naming: Same as {{blog}} - must use YYYY-MM-DD-Title format

Examples:

{{bloglist | ./pages/blog}}
{{bloglist | ./pages/blog | 0 | 10}}  ← Show first 10 post titles

Use case: Create a compact blog archive or sidebar widget

Form

Syntax: {{form | filename | field1 | field2 | field3 | ...}}

Creates a simple form that saves submissions to a CSV file. Useful for contact forms, newsletter signups, surveys, and other data collection.

Parameters:

Examples:

{{form | contact | Name | Email | Message}}
{{form | newsletter | Name | Email}}
{{form | survey | Name | Favorite Color | Comments}}

With CSS classes:

{{form | contact | Name | Email | class=>my-custom-form}}

How it works:

Viewing submissions:

Visit the CSV file URL directly to see submissions as a formatted HTML table:

http://yoursite.com/files/contact.csv

Features:

Security:

Helper Reference Quick Guide

Helper Purpose Example
{{a}} Internal link {{a | page | text}}
{{i}} Image {{i | image | alt}}
{{carousel}} Slideshow {{carousel:5000 | img1 | img2}}
{{insert}} Embed page {{insert | page}}
{{filelist}} Directory tree {{filelist | ./pages/docs}}
{{blog}} Blog with excerpts {{blog | ./pages/blog | 0 | 5}}
{{bloglist}} Blog titles only {{bloglist | ./pages/blog}}
{{form}} Form to CSV {{form | contact | Name | Email}}

Next Steps