Child Themes in OJS 3.3 & 3.4: Overriding Smarty Templates
Technical guide on building upgrade-safe child themes for OJS 3.3 and 3.4. Explains Smarty template overriding, LESS/CSS asset pipelines, and plugin registration.
Real Problem
Novice developers frequently hack core OJS template files to change layouts, only to have all their work wiped out during the next minor security patch.
Practical Solution
Build an isolated Child Theme plugin, register template overrides using identical relative directory paths, and manipulate Smarty template variables cleanly via PKP hook calls.
The Architecture of Template Overrides in PKP Framework
Open Journal Systems relies on Smarty 3 as its primary templating engine. The PKP framework implements an elegant template lookup priority queue:
1. Active Child Theme Directory (highest priority)
2. Parent Theme Directory
3. Core OJS Templates (templates/)
4. Shared PKP Library Templates (lib/pkp/templates/)
When you mirror an existing template path inside your child theme directory, OJS intercepts the request and serves your custom template, leaving the core application files completely pristine.
Step-by-Step Child Theme Construction
Step 1: Directory Setup
Create a new folder in your plugins directory:
plugins/themes/academicPress/
Inside this folder, create the following structure:
- index.php
- AcademicPressThemePlugin.inc.php (or .php in OJS 3.4)
- version.xml
- styles/
- custom.css
- templates/
- frontend/
- objects/
- article_details.tpl
Step 2: Defining version.xml
The version.xml file registers your theme with the OJS plugin registry:
<?xml version="1.0" encoding="UTF-8"?>
<version>
<application>academicPress</application>
<type>plugins.themes</type>
<release>1.0.0.0</release>
<date>2024-01-01</date>
<lazy-load>0</lazy-load>
<sitewide>0</sitewide>
</version>
Step 3: Creating the Theme Plugin Class
In AcademicPressThemePlugin.inc.php:
<?php
import('lib.pkp.classes.plugins.ThemePlugin');
class AcademicPressThemePlugin extends ThemePlugin {
public function init() {
$this->setParent('defaultthemeplugin');
$this->addStyle('academic-css', 'styles/custom.css');
$this->addScript('academic-js', 'js/main.js');
}
public function getDisplayName() {
return 'Academic Press Custom Theme';
}
public function getDescription() {
return 'Bespoke high-contrast child theme for academic publications.';
}
}
Step 4: Overriding the Article Details Template
To customize how article abstracts and galleys look, copy:
lib/pkp/templates/frontend/objects/article_details.tpl
into:
plugins/themes/academicPress/templates/frontend/objects/article_details.tpl
Now open your child template and add custom elements—such as a custom badge, social sharing buttons, or modified citation displays.
Step 5: Clearing Template Compilations
After making changes to Smarty templates, always delete cached files:
rm -rf cache/t_compile/*
Then navigate to Settings > Website > Appearance and select your new theme.
Step-by-Step Action Plan
Create Theme Plugin Directory Structure
Create plugins/themes/universityTheme/ with index.php, version.xml, and a ThemePlugin class file.
Define Parent Theme Inheritance
In the init() method, invoke $this->setParent("defaultthemeplugin") to inherit baseline functionality.
Mirror Template Directory Paths
Replicate target template paths inside your theme directory (e.g., templates/frontend/objects/article_details.tpl).
Inject Custom Smarty Markup
Edit the cloned template file to add custom HTML elements, structured schema tags, or visual badges.
Purge Template Cache & Activate
Clear cache/t_compile/ and enable the child theme in Settings > Website > Appearance.
Questions People Usually Ask
How does OJS decide which template file to render?
OJS checks the active theme directory first. If a template matching the requested path exists in the active child theme, it renders that file. If not, it falls back to the parent theme, and finally to core lib/pkp/templates/.
Can I add new template variables to Smarty from my child theme?
Yes! You can register a hook in your theme class using HookRegistry::register("TemplateManager::display", [$this, "addCustomVariables"]); to pass fresh data into Smarty.
Are LESS and Sass supported in OJS themes?
OJS 3 includes a built-in LESS compiler that compiles .less files automatically. For modern Sass/Tailwind development, compile assets externally into standard CSS and enqueue via $this->addStyle().
Need a Custom OJS Child Theme Built to Order?
AcademiaTech creates bespoke child themes that preserve 100% upgrade compatibility while transforming your journal’s visual presentation.