Skip to content

Template Customization Guide

Jump to bottom
Brent Cordis edited this page Mar 2, 2026 · 2 revisions

Template Customization Guide

This guide explains how to customize the display of your sermons, teachers, and series in Proclaim using templates and template codes.

Overview

Proclaim templates control how your content is displayed on the frontend. There are two levels of customization:

  1. Visual Layout Editor - Drag-and-drop interface for arranging elements without coding
  2. Template Code Files - PHP-level customization for complete control

Most users will find the Layout Editor sufficient for their needs. Template Code files are for advanced users who need custom PHP logic.

What Templates Control

Templates manage the presentation of:

  • Sermons List - How multiple sermons appear in a listing
  • Sermon Detail - Individual sermon display with full text and media
  • Teachers List - Directory of teachers/speakers
  • Teacher Detail - Individual teacher profile with their sermons
  • Series List - Collection of sermon series
  • Series Detail - Individual series with its sermons
  • Module Display - How sermons appear in modules

Each view type can have its own template with customized layout, colors, and content arrangement.

Layout Editor

The Layout Editor provides a visual, drag-and-drop interface for arranging content elements without writing code.

Accessing the Layout Editor

  1. Go to Components → Proclaim → Templates
  2. Click on a template to edit it
  3. Select the Layout Editor tab

The editor loads dynamically when you open the tab for faster page performance.

Using the Layout Editor

Available Elements

The editor shows all available content elements for your view type:

For Sermons (Messages):

Scripture: Scriptures, Secondary References, Scripture 1 & 2 (deprecated)

Message: Title, Date, Study Intro, Study Number, Duration

Teacher: Teacher Name, Teacher Image, Teacher Title, Teacher Short Bio, Teacher Long Bio, Teacher Large Image, Teacher All-in-One

Contact: Teacher Email, Teacher Website, Teacher Phone

Social: Teacher Facebook, Teacher Twitter, Teacher Blog

Series: Series Name, Series Thumbnail, Series Description

Media: Media Player, Thumbnail, Downloads

Metadata: Topics, Location, Message Type, Hits

Custom: Custom Text

For Teachers:

  • Teacher Name, Teacher Image, Teacher Link
  • Teacher-specific bio and contact fields

For Series:

  • Series Title, Series Description, Series Image, Series Link
  • Series-specific fields

Building Your Layout

  1. Add Elements - Drag elements from the "Available Elements" panel into the layout grid
  2. Arrange in Rows - Elements are organized in rows, each row can contain multiple elements
  3. Reorder - Drag elements to rearrange them within or between rows
  4. Remove - Click the remove icon (×) to delete unwanted elements

Element Settings

Click the settings icon (⚙) on any element to configure:

  • HTML Element - Wrap content in P, H1-H5, Blockquote, or DIV tags
  • Columns to Span - How many grid columns the element occupies (1-12)
  • Link Type - What happens when clicked:
    • No Link
    • Link to Details
    • Link to Media File
    • Link to Download
    • Link to Teacher's Profile
    • Link to First Article
    • Link to VirtueMart
    • Link to DOCman
    • Link to Series
  • Custom Class - Add CSS classes or inline styles (e.g., class="my-class" or style="color: red;")
  • Date Format - For date elements, choose from 10+ format options
  • Show Verses - For scripture elements, show chapters only or chapters with verses

View Settings

Some layout contexts include view-level settings:

  • Default ordering (ascending/descending)
  • Show/hide archived messages
  • Show/hide archive badge
  • Filter display options

Saving Your Layout

Changes are saved when you click Save or Save & Close on the template form. The Layout Editor reads from and writes to the template's existing form fields, so no special save action is needed.

Template Code Files

Template Code files give you complete control by creating custom PHP template files. This is for advanced users comfortable with PHP and Joomla template development.

Understanding Template Types

When creating a template code file, you select a type that determines where it's used:

Type Name Location Purpose
1 Sermons List site/tmpl/Cwmsermons/ Multiple sermon listing
2 Sermon Detail site/tmpl/Cwmsermon/ Single sermon view
3 Teachers List site/tmpl/Cwmteachers/ Teacher directory
4 Teacher Detail site/tmpl/Cwmteacher/ Single teacher profile
5 Series List site/tmpl/Cwmseriesdisplays/ Series directory
6 Series Detail site/tmpl/Cwmseriesdisplay/ Single series view
7 Module modules/mod_proclaim/tmpl/ Module display

Reserved Filenames

These filenames are reserved and cannot be used for custom templates:

  • main - Core template file
  • simple - Simplified view template
  • custom - System custom file
  • formheader - Form header partial
  • formfooter - Form footer partial

Choose a descriptive name like mycustom, church2024, or minimal.

Creating a Template Code File

  1. Go to Components → Proclaim → Template Files
  2. Click New
  3. Enter a unique Filename (without .php extension)
  4. Select the Type (1-7 from table above)
  5. Enter your PHP code in the Template Code field
  6. Click Save

The file is automatically created in the correct location as default_{filename}.php.

Available Variables

The view provides these variables to your template:

All List Views (Types 1, 3, 5)

$this->items          // Array of items to display
$this->pagination     // Pagination object
$this->params         // Template parameters
$this->page->pagelinks // Pagination links HTML
$this->page->limitbox  // Results per page selector
$this->page->searchtools // Search/filter form

Sermon List (Type 1)

Each item in $this->items has:

$study->studytitle       // Sermon title
$study->studydate        // Formatted date
$study->studyintro       // Introduction text
$study->scripture1       // Primary scripture reference
$study->scripture2       // Secondary scripture
$study->media            // Media player/links HTML
$study->duration         // Media duration
$study->topics           // Topics list
$study->detailslink      // Link to details page
$study->teachername      // Teacher name
$study->teacherimage     // Teacher image HTML
$study->location_text    // Location name
$study->hits             // View count
$study->study_thumbnail  // Sermon thumbnail
$study->studynumber      // Study number
$study->slug             // URL-safe identifier

Sermon Detail (Type 2)

$this->item->studytext    // Full sermon text
$this->item->studytitle   // Sermon title
$this->passage            // Scripture passage text
$this->related            // Related sermons HTML
$this->page->print        // Print button
$this->page->social       // Social sharing buttons

Teacher List (Type 3)

Each item in $this->items has:

$teacher->teachername  // Teacher name
$teacher->image        // Teacher image HTML
$teacher->teacherlink  // Link to teacher detail

Teacher Detail (Type 4)

$this->item->title           // Teacher title
$this->item->information     // Full biography
$this->item->short           // Short bio/intro
$this->item->image           // Teacher image
$this->item->phone           // Phone number
$this->item->email           // Email address
$this->item->website         // Website URL
$this->teacherstudies        // Array of teacher's sermons

Series List (Type 5)

Each item in $this->items has:

$series->series_text   // Series name
$series->description   // Series description
$series->image         // Series image HTML
$series->serieslink    // Link to series detail

Series Detail (Type 6)

$this->page->series_text   // Series title
$this->page->image         // Series image
$this->page->description   // Series description
$this->page->teachername   // Primary teacher
$this->seriesstudies       // Array of sermons in series

Module (Type 7)

$list   // Array of sermon items
$link   // Module link URL

Code Snippet Helper

The Template Code editor includes a Code Snippets panel with ready-to-use code blocks:

Study Loop Snippets:

  • foreach ($this->items as $study) { } - Loop through items
  • echo $study->studytitle; - Display title
  • echo $study->studydate; - Display date
  • Plus 15+ more sermon fields

Page Control Snippets:

  • Search tools, pagination, limit box, intro text

Sermon Detail Snippets:

  • Full text, passage, related, print, social sharing

Teacher/Series Snippets:

  • Specialized fields for each view type

Click any snippet button to insert the code at your cursor position.

Example Template Code

Simple sermon list:

<?php defined('_JEXEC') or die; ?>

<div class="sermon-list">
<?php foreach ($this->items as $study): ?>
    <article class="sermon-item">
        <h2><?php echo $study->studytitle; ?></h2>
        <p class="sermon-meta">
            <span class="teacher"><?php echo $study->teachername; ?></span>
            <span class="date"><?php echo $study->studydate; ?></span>
        </p>
        <div class="scripture"><?php echo $study->scripture1; ?></div>
        <div class="media"><?php echo $study->media; ?></div>
    </article>
<?php endforeach; ?>
</div>

<div class="pagination">
    <?php echo $this->page->pagelinks; ?>
</div>

Custom sermon detail:

<?php defined('_JEXEC') or die; ?>

<article class="sermon-detail">
    <header>
        <h1><?php echo $this->item->studytitle; ?></h1>
        <div class="sermon-meta">
            <?php echo $this->item->studydate; ?> |
            <?php echo $this->item->teachername; ?>
        </div>
    </header>

    <div class="sermon-content">
        <?php echo $this->item->studytext; ?>
    </div>

    <?php if ($this->passage): ?>
        <aside class="passage">
            <h3>Scripture Passage</h3>
            <?php echo $this->passage; ?>
        </aside>
    <?php endif; ?>

    <footer>
        <?php echo $this->page->print; ?>
        <?php echo $this->page->social; ?>
    </footer>
</article>

Security Requirement

All template code files must include this security check as the first line:

<?php defined('_JEXEC') or die;

Proclaim automatically adds this if you forget it, but it's best practice to include it yourself.

Template Settings

Templates have numerous configuration options accessible from the template edit screen:

Color Settings

These colors control the visual theme and are available as CSS variables:

  • Back Color - Primary background color
  • Front Color - Primary text/foreground color
  • Light Color - Accent/highlight color
  • Screen Color - Screen/modal backgrounds
  • Popup Background - Popup/tooltip backgrounds
  • Teacher Display Color - Color for teacher elements in the Layout Editor
  • Series Display Color - Color for series elements in the Layout Editor
  • Download Button Color - Color for download buttons
  • Media Button Color - Color for media player buttons

Colors use the ColorPicker field, which provides a tabbed interface: a "Named Colors" tab with 140+ CSS color names (searchable), and a "Custom Color" tab for hex values.

Template Parameters

Each template has settings for:

  • Media Display - How audio/video players appear
  • Link Behavior - What happens when elements are clicked
  • Date Formats - How dates are displayed
  • Show/Hide Controls - Which elements appear
  • Filter Options - Available search/filter fields
  • Social Sharing - Enabled sharing services

These parameters are accessible in template code via $this->params->get('setting_name').

Assign to Menu Items

After creating a template, assign it to menu items:

  1. Go to Menus and edit a Proclaim menu item
  2. In the Template dropdown, select your custom template
  3. Save the menu item

Best Practices

Maintaining Customizations

Template Updates:

  • Built-in templates may be updated with component upgrades
  • Custom template code files you create are never overwritten
  • Layout Editor settings are stored in the database and preserved

Version Control:

  • Export templates before major component updates
  • Keep backups of custom template code
  • Document any custom modifications

Performance Tips

  • Use the Layout Editor for simple arrangements (faster than PHP templates)
  • Avoid complex logic in templates - use Models/Helpers for heavy processing
  • Cache expensive operations when writing custom templates
  • Test templates with large datasets to ensure pagination works correctly

Accessibility

  • Use semantic HTML elements (header, article, nav)
  • Include ARIA labels for interactive elements
  • Ensure color contrast meets WCAG standards
  • Test keyboard navigation in custom templates

Responsive Design

  • Use Bootstrap 5 classes (built into Joomla)
  • Test layouts on mobile, tablet, and desktop
  • Consider using Bootstrap's grid system for columns
  • The Layout Editor automatically generates responsive layouts

Troubleshooting

Template not appearing:

  • Check that it's assigned to the menu item
  • Verify the template is published
  • Clear Joomla cache (System → Clear Cache)

Layout Editor changes not saving:

  • Ensure JavaScript is enabled
  • Check browser console for errors
  • Try disabling browser extensions
  • Clear browser cache and reload

Variables not showing data:

  • Verify you're using the correct variable for the view type
  • Check that data exists (teacher might not have an image, etc.)
  • Use var_dump($this->item) to see all available properties

Styling issues:

  • Check that custom classes are valid
  • Verify CSS is loading (check browser developer tools)
  • Ensure color hex codes start with #
  • Use browser inspector to debug layout problems

Additional Resources

For component-specific questions, visit the Proclaim Support Forum.

Getting Started

Guides

Development

Help Screens

Clone this wiki locally