Skip to content

Template Reference

Overview

The Gold Standard Module uses Smarty 3 templating with a structured organization that separates frontend, admin, and email templates. This reference covers the template architecture, available variables, and customization patterns.

Template Architecture

flowchart TB
    subgraph "Template Hierarchy"
        A[Theme Templates] --> B[Module Templates]
        B --> C[Frontend Templates]
        B --> D[Admin Templates]
        B --> E[Email Templates]
        C --> F[Partials]
        D --> F
    end

    subgraph "Override System"
        G[themes/mytheme/modules/goldstandard/] --> H[Override Priority]
        I[modules/goldstandard/templates/] --> H
    end

Directory Structure

modules/goldstandard/templates/
├── blocks/                    # Block templates
│   ├── block_latest.tpl
│   ├── block_popular.tpl
│   ├── block_categories.tpl
│   └── block_tags.tpl
├── frontend/                  # User-facing templates
│   ├── index.tpl
│   ├── article.tpl
│   ├── category.tpl
│   ├── search.tpl
│   └── partials/
│       ├── article_card.tpl
│       ├── pagination.tpl
│       └── breadcrumb.tpl
├── admin/                     # Administration templates
│   ├── index.tpl
│   ├── article_list.tpl
│   ├── article_form.tpl
│   ├── category_list.tpl
│   └── settings.tpl
└── mail/                      # Email templates
    ├── notify_new_article.tpl
    ├── notify_new_comment.tpl
    └── notify_article_approved.tpl

Template Variables

Global Variables

Available in all templates:

Variable Type Description
$xoops_sitename string Site name
$xoops_url string Base URL
$xoops_rootpath string Server root path
$xoops_langcode string Current language code
$xoops_charset string Character encoding
$xoops_theme string Active theme name
$xoops_isuser bool User logged in status
$xoops_isadmin bool User is module admin
$xoops_userid int Current user ID
$xoops_uname string Current username

Module Variables

Variable Type Description
$module_name string Module display name
$module_dirname string Module directory
$module_url string Module base URL
$module_config array Module configuration
$module_version string Module version

Article Variables

{* Article object properties *}
{$article.id}              {* ULID identifier *}
{$article.title}           {* Article title *}
{$article.slug}            {* URL-friendly slug *}
{$article.content}         {* Full HTML content *}
{$article.excerpt}         {* Short excerpt *}
{$article.author_id}       {* Author user ID *}
{$article.author_name}     {* Author display name *}
{$article.author_avatar}   {* Author avatar URL *}
{$article.created_at}      {* Creation timestamp *}
{$article.published_at}    {* Publication timestamp *}
{$article.updated_at}      {* Last update timestamp *}
{$article.status}          {* draft|published|archived *}
{$article.view_count}      {* Number of views *}
{$article.comment_count}   {* Number of comments *}
{$article.rating}          {* Average rating *}
{$article.featured_image}  {* Featured image URL *}
{$article.categories}      {* Array of categories *}
{$article.tags}            {* Array of tags *}
{$article.url}             {* Canonical URL *}
{$article.edit_url}        {* Admin edit URL *}

Category Variables

{$category.id}             {* Category ID *}
{$category.name}           {* Category name *}
{$category.slug}           {* URL slug *}
{$category.description}    {* Category description *}
{$category.parent_id}      {* Parent category ID *}
{$category.article_count}  {* Number of articles *}
{$category.image}          {* Category image URL *}
{$category.url}            {* Category page URL *}
{$category.children}       {* Child categories array *}

Smarty Syntax Reference

Variables and Modifiers

{* Basic output *}
{$article.title}

{* With modifier *}
{$article.title|escape}
{$article.title|truncate:50:'...'}
{$article.content|strip_tags|truncate:200}

{* Date formatting *}
{$article.published_at|date_format:'%B %d, %Y'}
{$article.created_at|date_format:$xoops_config.dateformat}

{* Number formatting *}
{$article.view_count|number_format}

{* Default values *}
{$article.excerpt|default:$article.content|truncate:200}

{* Chained modifiers *}
{$article.title|escape|capitalize|truncate:60}

Control Structures

{* Conditionals *}
{if $article.status == 'published'}
    <span class="badge badge-success">Published</span>
{elseif $article.status == 'draft'}
    <span class="badge badge-warning">Draft</span>
{else}
    <span class="badge badge-secondary">Archived</span>
{/if}

{* Loops *}
{foreach $articles as $article}
    <article class="article-card">
        <h2>{$article.title|escape}</h2>
        <p>{$article.excerpt}</p>
    </article>
{foreachelse}
    <p>No articles found.</p>
{/foreach}

{* Loop with index *}
{foreach $categories as $index => $category}
    <li class="{if $index == 0}first{/if}">
        {$category.name}
    </li>
{/foreach}

{* Loop properties *}
{foreach $items as $item}
    {if $item@first}First item{/if}
    {if $item@last}Last item{/if}
    Item {$item@iteration} of {$item@total}
{/foreach}

Including Templates

{* Include partial *}
{include file='db:goldstandard_partials_article_card.tpl' article=$article}

{* Include with variables *}
{include file='db:goldstandard_partials_pagination.tpl'
    current_page=$current_page
    total_pages=$total_pages
    base_url=$category.url
}

{* Include from theme (with fallback) *}
{include file='db:goldstandard_frontend_article.tpl'}

Blocks and Inheritance

{* Define a block in parent template *}
{block name='content'}
    Default content here
{/block}

{* Override in child template *}
{extends file='db:goldstandard_layout.tpl'}

{block name='content'}
    Custom content for this page
{/block}

{* Append to parent block *}
{block name='sidebar' append}
    Additional sidebar content
{/block}

Custom Smarty Functions

Module-Specific Functions

{* Generate article URL *}
{goldstandard_url type='article' id=$article.id slug=$article.slug}

{* Permission check *}
{if {goldstandard_can action='edit' article=$article}}
    <a href="{$article.edit_url}">Edit</a>
{/if}

{* Format relative time *}
{goldstandard_timeago timestamp=$article.published_at}
{* Output: "2 hours ago" *}

{* Rating display *}
{goldstandard_rating value=$article.rating max=5 readonly=true}

Registering Custom Functions

// In module bootstrap
$xoopsTpl->registerPlugin('function', 'goldstandard_url', function($params, $smarty) {
    $type = $params['type'] ?? 'article';
    $id = $params['id'] ?? '';
    $slug = $params['slug'] ?? '';

    return match($type) {
        'article' => XOOPS_URL . "/modules/goldstandard/article/{$slug}-{$id}.html",
        'category' => XOOPS_URL . "/modules/goldstandard/category/{$slug}.html",
        default => XOOPS_URL . "/modules/goldstandard/"
    };
});

Template Override System

Theme Override Locations

Templates can be overridden in your theme:

themes/mytheme/modules/goldstandard/
├── blocks/
│   └── block_latest.tpl      # Override block template
├── goldstandard_article.tpl   # Override article template
└── goldstandard_index.tpl     # Override index template

Override Priority

  1. themes/{theme}/modules/{module}/ (highest priority)
  2. modules/{module}/templates/ (default)

Creating an Override

{* themes/mytheme/modules/goldstandard/goldstandard_article.tpl *}

{* Completely custom layout *}
<article class="my-custom-article">
    <header>
        <h1 class="title">{$article.title|escape}</h1>
        <div class="meta">
            By {$article.author_name} on {$article.published_at|date_format:'%F'}
        </div>
    </header>

    <figure class="featured-image">
        <img src="{$article.featured_image}" alt="{$article.title|escape}">
    </figure>

    <div class="content prose">
        {$article.content}
    </div>

    <footer>
        {include file='db:goldstandard_partials_tags.tpl' tags=$article.tags}
        {include file='db:goldstandard_partials_share.tpl' article=$article}
    </footer>
</article>

Best Practices

Security

{* Always escape user-generated content *}
{$user_input|escape:'html'}

{* For URLs *}
<a href="{$url|escape:'url'}">Link</a>

{* For JavaScript strings *}
<script>var title = '{$article.title|escape:'javascript'}';</script>

{* For HTML attributes *}
<div data-title="{$article.title|escape:'htmlall'}">

Performance

{* Cache expensive blocks *}
{cachefragment name="sidebar_categories" ttl=3600}
    {include file='db:goldstandard_partials_category_tree.tpl'}
{/cachefragment}

{* Lazy load images *}
<img src="{$article.featured_image}" loading="lazy" alt="{$article.title|escape}">

Accessibility

{* Proper heading hierarchy *}
<h1>{$page_title}</h1>
{foreach $articles as $article}
    <h2>{$article.title}</h2>
{/foreach}

{* ARIA labels *}
<nav aria-label="Breadcrumb">
    {include file='db:goldstandard_partials_breadcrumb.tpl'}
</nav>

{* Alt text for images *}
<img src="{$image.url}" alt="{$image.alt|escape|default:$article.title}">