PKP Theming Guide

https://docs.pkp.sfu.ca/pkp-theming-guide/en/
Admin
The PKP Theming Guide is a comprehensive introduction to building custom themes, templates, and...
Tokens:11,943
Snippets:164
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize Theme Configuration

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

The init() method is the entry point for theme setup, where styles, scripts, and hooks are registered.

```php
/**
 * Initialize the theme's styles, scripts and hooks. This is only run for
 * the currently active theme.
 *
 * @return null
 */
public function init() {
    $this->addStyle('my-custom-style', 'styles/index.less');
}
```

--------------------------------

### List theme style files

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/css-less.html

Example file structure for a custom theme plugin using modular LESS files.

```text
styles/index.less
styles/variables.less
styles/structure.less
styles/forms.less
```

--------------------------------

### Install Bootstrap3 via Git

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-bootstrap3.html

Use this command to add the Bootstrap3 theme as a git submodule within an existing OJS installation.

```bash
git submodule add https://github.com/pkp/bootstrap3.git plugins/themes/bootstrap3
```

--------------------------------

### init()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

The init() method is the entry point for theme configuration. It is executed only for the currently active theme and is where all other theme API methods should be called.

```APIDOC
## init()

### Description
Initialize the theme's styles, scripts and hooks. This is only run for the currently active theme.

### Method
public function init()

### Returns
- **null**
```

--------------------------------

### Theme File Structure

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-setup.html

The standard directory layout for a theme plugin named tutorial-theme.

```text
/plugins/themes/tutorial-theme/index.php
/plugins/themes/tutorial-theme/TutorialThemePlugin.inc.php
/plugins/themes/tutorial-theme/version.xml
/plugins/themes/tutorial-theme/locale/en_US/locale.po
/plugins/themes/tutorial-theme/styles/index.less
/plugins/themes/tutorial-theme/styles/variables.less
/plugins/themes/tutorial-theme/styles/structure.less
/plugins/themes/tutorial-theme/styles/forms.less
```

--------------------------------

### Retrieve and apply a theme option

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Use getOption to fetch a value and modifyStyle to pass it to the LESS compiler.

```php
public function init() {
	$baseColour = $this->getOption('baseColour');
	$this->modifyStyle(
		'stylesheet',
		['addLessVariables' => "@bg-base:$baseColour;"]
	);
}
```

--------------------------------

### Initialize theme styles

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/child-themes.html

The init method is used to register theme-specific stylesheets.

```php
	/**
	 * Load the custom styles for our theme
	 * @return null
	 */
	public function init() {
        $this->addStyle('stylesheet', 'styles/index.less');
	}
```

--------------------------------

### Theme Entry Point

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-setup.html

The index.php file used to instantiate the theme plugin class.

```php
<?php
require_once('TutorialThemePlugin.inc.php');
return new TutorialThemePlugin();
?>
```

--------------------------------

### Iterate over all theme options

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Use getOptionsConfig to retrieve all defined theme options for iteration.

```php
public function init() {
	$allOptions = $this->getOptionsConfig();
	foreach ((array) $allOptions as $option) {
		...
	}
}
```

--------------------------------

### Style Initialization Method

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-setup.html

The init method used to register the main LESS stylesheet.

```php
public function init() {
        $this->addStyle('stylesheet', 'styles/index.less');
    }
```

--------------------------------

### Initialize Child Theme with modifyStyle

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-bootstrap3.html

Use the init method to set the parent theme and inject custom LESS variables via the modifyStyle method.

```php
    /**
     * Load the custom styles for our theme
     * @return null
     */
    public function init() {
        $this->setParent('bootstrapthreethemeplugin');
        $this->modifyStyle('bootstrap', array('addLess' => array('styles/variables.less')));
    }
```

--------------------------------

### Define swatch file header

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-bootstrap3.html

Add copyright and licensing information to the new LESS file.

```less
/**
 * @file plugins/themes/bootstrap3/myswatch.less
 *
 * Copyright (c) 2014-2024 Simon Fraser University Library
 * Copyright (c) 2003-2024 John Willinsky
 * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
 *
 * @brief Stylesheet for the My Theme Bootstrap theme.
 */
```

--------------------------------

### addOption(string $name, string $component, array $args)

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Registers a new theme option within the theme's init() method. This method defines the configuration field type, label, description, and default values.

```APIDOC
## addOption(string $name, string $component, array $args)

### Description
Registers a configuration option for a theme. This must be called within the theme's `init()` method.

### Parameters
- **name** (string) - The unique identifier for the theme option.
- **component** (string) - The UI component class name (e.g., 'FieldColor', 'FieldOptions', 'FieldText').
- **args** (array) - Configuration settings including 'label', 'description', 'default', and 'options' for selection fields.

### Usage Example
```php
public function init() {
	$this->addOption('baseColour', 'FieldColor', [
		'label' => __('plugins.themes.default.option.colour.label'),
		'description' => __('plugins.themes.default.option.colour.description'),
		'default' => '#1E6292',
	]);
}
```
```

--------------------------------

### Register swatch in locale file

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-bootstrap3.html

Add the new theme name to the locale XML file for display.

```xml
 <message key="plugins.themes.bootstrap3.options.bootstrapTheme.myswatch">My Swatch</message>
```

--------------------------------

### Clear swatch configuration files

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-bootstrap3.html

Empty these files to prepare them for new swatch definitions.

```text
plugins/themes/bootstrap3/bootstrap-themes/myswatch/bootswatch.less
plugins/themes/bootstrap3/bootstrap-themes/myswatch/variables.less
```

--------------------------------

### Registering and applying theme options

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Use this pattern to add a radio-style theme option and conditionally modify stylesheets based on the selected value.

```php
public function init() {

	// Add the option
	$this->addOption('typography', 'FieldOptions', [
		'type' => 'radio',
		'label' => __('plugins.themes.default.option.typography.label'),
		'description' => __('plugins.themes.default.option.typography.description'),
		'options' => [
			[
				'value' => 'notoSans',
				'label' => __('plugins.themes.default.option.typography.notoSans'),
			],
			[
				'value' => 'notoSerif',
				'label' => __('plugins.themes.default.option.typography.notoSerif'),
			],
		],
		'default' => 'notoSans',
	]);

	// Load the correct google font
	if ($this->getOption('typography') === 'notoSerif') {
		$this->addStyle(
			'fontNotoSerif',
			'//fonts.googleapis.com/css?family=Noto+Serif:400,400i,700,700i',
			['baseUrl' => '']
		);
		$this->modifyStyle(
			'stylesheet',
			['addLessVariables' => '@font: "Noto Serif", serif;']
		);
	} else {
		$this->addStyle(
			'fontNotoSans',
			'//fonts.googleapis.com/css?family=Noto+Sans:400,400i,700,700i',
			['baseUrl' => '']
		);
		$this->modifyStyle(
			'stylesheet',
			['addLessVariables' => '@font: "Noto Sans", sans-serif;']
		);
	}
}
```

--------------------------------

### Manage color contrast

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Use isColourDark to check brightness and conditionally set LESS variables for text contrast.

```php
public function init() {

		// Set the background color
		$additionalLessVariables[] = '@bg-base:' . $this->getOption('baseColour') . ';';

		// Set the text to white if the background is too dark
    if (!$this->isColourDark($this->getOption('baseColour'))) {
        $additionalLessVariables[] = '@text-bg-base:white;';
    }
}
```

--------------------------------

### Import swatch styles in LESS

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-bootstrap3.html

Update the LESS import references to point to the new swatch files.

```less
@import "bootstrap.less";
@import "../bootstrap-themes/myswatch/variables.less";
@import "../bootstrap-themes/myswatch/myswatch.less";
```

--------------------------------

### Configure a child theme with a parent

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/child-themes.html

Use setParent to designate a parent theme and ensure unique stylesheet identifiers to avoid conflicts.

```php
	/**
	 * Load the custom styles for our theme
	 * @return null
	 */
	public function init() {

        // Use the parent theme's unique plugin slug
        $this->setParent('defaultthemeplugin');

        // Change the ID of this stylesheet slug to
        // `child-stylesheet`. This ensures that it
        // won't clash with the parent's stylesheet.
        $this->addStyle('child-stylesheet', 'styles/index.less');
	}
```

--------------------------------

### Modularize LESS files

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/css-less.html

Split styles into separate files and combine them using the @import directive.

```less
// styles/variable.less
@background: red;
```

```less
// styles/structure.less
.pkp_structure_head,
.pkp_structure_footer {
  background: @background;
}
```

```less
// styles/forms.less
button {
  border-color: @background;
}
```

```less
// styles/index.less
// Now we can combine all of these files into one.
@import "variables"
@import "structure"
@import "forms"
```

--------------------------------

### Add a color picker theme option

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Registers a color picker field within the theme's init() method.

```php
public function init() {
	$this->addOption('baseColour', 'FieldColor', [
		'label' => __('plugins.themes.default.option.colour.label'),
		'description' => __('plugins.themes.default.option.colour.description'),
		'default' => '#1E6292',
	]);
}
```

--------------------------------

### Documenting template variables with @uses

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/template-variables.html

Use the @uses prefix in the header of Smarty template files to document variables passed to the template.

```smarty
{**
 * templates/frontend/pages/article.tpl
 *
 * Copyright (c) 2014-2016 Simon Fraser University Library
 * Copyright (c) 2003-2016 John Willinsky
 * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
 *
 * @brief Display the page to view an article with all of it's details.
 *
 * @uses $article Article This article
 * @uses $issue Issue The issue this article is assigned to
 * @uses $section Section The journal section this article is assigned to
 * @uses $journal Journal The journal currently being viewed.
 *}
```

--------------------------------

### Add a JavaScript file

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Use addScript to include JavaScript files in the theme, with optional arguments for context and priority.

```php
public function init() {
    $this->addScript('my-javascript', 'js/main.js');
}
```

```php
/**
 * Add a script to load with this theme
 *
 * @param $name string A name for this script
 * @param $script string The script to be included. Should be path relative
 *   to the theme or, if the `inline` argument is included, script data to
 *   be output.
 * @param $args array Optional arguments hash. Supported args:
 *   `context` string Whether to load this on the `frontend` or `backend`.
 *      default: frontend
 *   `priority` int Controls order in which scripts are printed
 *      default: STYLE_SEQUENCE_NORMAL
 *   `inline` bool Whether the $script value should be output directly as
 *      script data. Used to pass backend data to the scripts.
 */
public function addScript($name, $script, $args = array()) { ... }
```

--------------------------------

### Localized Theme Methods

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-setup.html

Updated class methods to retrieve translated strings using the __() helper.

```php
/**
     * Get the display name of this theme
     * @return string
     */
    function getDisplayName() {
        return __('plugins.themes.tutorial-theme.name');
    }

    /**
     * Get the description of this plugin
     * @return string
     */
    function getDescription() {
        return __('plugins.themes.tutorial-theme.description');
    }
```

--------------------------------

### Theme Version Configuration

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-setup.html

The version.xml file required for OJS/OMP to recognize and load the theme.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE version SYSTEM "../../../lib/pkp/dtd/pluginVersion.dtd">
<version>
    <!-- The application value should match the directory name of the theme -->
    <application>tutorial-theme</application>
    <type>plugins.themes</type>
    <release>1.0.0.0</release>
    <date>2016-11-21</date>
    <lazy-load>1</lazy-load>
    <class>TutorialThemePlugin</class>
</version>
```

--------------------------------

### Set a parent theme

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Configures the current theme as a child of another specified theme.

```php
public function init() {
    $this->setParent('defaultthemeplugin');
}
```

--------------------------------

### Theme Localization File

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-setup.html

The locale.po file used for defining translatable strings.

```po
"Project-Id-Version: \n"
"Report-Msgid-Bugs-To: \n"
"Last-Translator: \n"
"Language-Team: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2020-06-19T13:50:00+00:00\n"
"PO-Revision-Date: 2020-06-19T13:50:00+00:00\n"
"Language: \n"

msgid "plugins.themes.tutorial-theme.name"
msgstr "Tutorial Theme"

msgid "plugins.themes.tutorial-theme.description"
msgstr "An example theme for OJS or OMP built with our amazing documentation."
```

--------------------------------

### Update theme variables

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/css-less.html

Update a single variable to change branding across all imported files.

```less
// styles/variable.less
@background: blue;
```

--------------------------------

### addMenuArea()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Registers one or more menu areas for the theme.

```APIDOC
## addMenuArea($areas)

### Description
Registers menu areas to display navigation menus. Can accept a single string or an array of strings.

### Parameters
- **$areas** (string|array) - Required - The name of the menu area or an array of menu area names.
```

--------------------------------

### Add Stylesheets to Theme

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Methods for adding LESS or CSS files to a theme via the addStyle method.

```php
public function init() {
    $this->addStyle('my-custom-style', 'styles/index.less');
}
```

```php
public function init() {
    $this->addStyle('my-custom-style', 'styles/stylesheet.css');
}
```

--------------------------------

### Register styles in Theme API

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/css-less.html

Use the addStyle method within the init function of a ThemePlugin to load LESS files.

```php
class DefaultThemePlugin extends ThemePlugin {
  public function init() {
    // The second parameter, 'styles/index.less',
    // must point to a LESS file in your theme.
    $this->addStyle('stylesheet', 'styles/index.less');
  }
}
```

--------------------------------

### AddStyle Method Signature

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

The full method signature for addStyle, including supported optional arguments.

```php
/**
 * Add a stylesheet to load with this theme
 *
 * Style paths with a .less extension will be compiled and redirected to
 * the compiled file.
 *
 * @param $name string A name for this stylesheet
 * @param $style string The stylesheet. Should be a path relative to the
 *   theme directory or, if the `inline` argument is included, style data to
 *   be output.
 * @param $args array Optional arguments hash. Supported args:
 *   'context': Whether to load this on the `frontend`, `backend`, or `htmlGalley`.
 *      default: `frontend`
 *   'priority': Controls order in which styles are printed
 *   'addLess': Additional LESS files to process before compiling. Array
 *   'addLessVariables': A string containing additional LESS variables to
 *      parse before compiling. Example: "@bg:#000;"
 *   `inline` bool Whether the $style value should be output directly as
 *      style data.
 */
public function addStyle($name, $style, $args = array()) { ... }
```

--------------------------------

### addScript()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Registers a JavaScript file to be loaded with the theme.

```APIDOC
## addScript($name, $script, $args)

### Description
Add a JavaScript file to the theme. The script path should be relative to the theme directory.

### Parameters
- **$name** (string) - Required - A unique name for this script.
- **$script** (string) - Required - The path to the script file or script data if `inline` is true.
- **$args** (array) - Optional - Configuration arguments:
  - **context** (string) - Optional - Load location ('frontend' or 'backend'). Default: 'frontend'.
  - **priority** (int) - Optional - Controls print order. Default: STYLE_SEQUENCE_NORMAL.
  - **inline** (bool) - Optional - Whether the script value should be output directly as script data.
```

--------------------------------

### Add a text field theme option

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Registers a simple text input field for theme configuration.

```php
public function init() {
	$this->addOption('callToAction', 'FieldText', [
		'label' => __('plugins.themes.default.option.callToAction.label'),
		'default' => false,
	]);
}
```

--------------------------------

### Generate publication version links

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/publication-versions.html

Create URLs for the most recent version or iterate through all published versions to provide specific links.

```smarty
{url page="article" op="view" path=$article->getBestId()}
```

```smarty
{foreach from=$article->getData('publications') item=$iPublication}
	{url page="article" op="view" path=$article->getBestId()|to_array:"version":$iPublication->getId()}
{/foreach}
```

--------------------------------

### Display site title

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/html-smarty.html

Access the global $siteTitle variable to display the name of the site.

```smarty
<p>Welcome to {$siteTitle}!</p>
```

--------------------------------

### Modify existing backend styles

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-backend.html

Use the modifyStyle method to inject additional LESS files into the existing pkpLib stylesheet.

```php
    public function init() {
        $this->modifyStyle('pkpLib', array('addLess' => array('styles/index.less')));
    }
```

--------------------------------

### Inject custom styles into the backend

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-backend.html

Use the addStyle method with the 'backend' context to include custom stylesheets in the editorial interface.

```php
    public function init() {
        $this->addStyle('my-custom-style', 'styles/index.less', array( 'contexts' => 'backend' ));
    }
```

--------------------------------

### addStyle()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Adds a stylesheet to the theme. Supports both LESS files (which are compiled automatically) and pre-compiled CSS files.

```APIDOC
## addStyle($name, $style, $args = array())

### Description
Add a stylesheet to load with this theme. Style paths with a .less extension will be compiled and redirected to the compiled file.

### Parameters
- **$name** (string) - Required - A name for this stylesheet
- **$style** (string) - Required - The stylesheet path relative to the theme directory or style data if inline is used
- **$args** (array) - Optional - Optional arguments hash:
    - 'context' (string): Load on 'frontend', 'backend', or 'htmlGalley'. Default: 'frontend'
    - 'priority' (int): Controls order in which styles are printed
    - 'addLess' (array): Additional LESS files to process before compiling
    - 'addLessVariables' (string): Additional LESS variables to parse before compiling
    - 'inline' (bool): Whether the $style value should be output directly as style data
```

--------------------------------

### Access context settings

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/html-smarty.html

Use the $currentContext variable to retrieve settings like the localized name of the journal or press.

```smarty
<p>Welcome to {$currentContext->getLocalizedName()}</p>
```

--------------------------------

### Access article data

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/html-smarty.html

Retrieve specific article details using the $article variable available in article-specific templates.

```smarty
<h1 class="article-title">{$article->getLocalizedTitle()}</h1>
```

--------------------------------

### Add a radio selection theme option

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Registers a radio button group for selecting from a predefined list of options.

```php
public function init() {
	$this->addOption('typography', 'FieldOptions', [
		'type' => 'radio',
		'label' => __('plugins.themes.default.option.typography.label'),
		'description' => __('plugins.themes.default.option.typography.description'),
		'options' => [
			[
				'value' => 'notoSans',
				'label' => __('plugins.themes.default.option.typography.notoSans'),
			],
			[
				'value' => 'notoSerif',
				'label' => __('plugins.themes.default.option.typography.notoSerif'),
			],
		],
		'default' => 'notoSans',
	]);
}
```

--------------------------------

### Assign Announcements to All Templates

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/advanced-custom-data.html

Fetches and assigns the latest announcements to all templates if enabled for the current journal.

```php
class DocsThemePlugin extends ThemePlugin {
	/**
	 * Initialize the theme
	 */
	public function init() {
		HookRegistry::register ('TemplateManager::display', array($this, 'loadTemplateData'));
	}

	/**
	 * Fired when the `TemplateManager::display` hook is called.
	 *
	 * @param string $hookname
	 * @param array $args [$templateMgr, $template, $sendContentType, $charset, $output]
	 */
	public function loadTemplateData($hookName, $args) {

		// Retrieve the TemplateManager
		$templateMgr = $args[0];

		// Attach the latest 3 announcements if they're enabled for this journal
		$request = Application::get()->getRequest();
		$journal = $request->getJournal();
		if ($journal && $journal->getSetting('enableAnnouncements') {
			$announcementDao = DAORegistry::getDAO('AnnouncementDAO');
			$announcements =& $announcementDao->getNumAnnouncementsNotExpiredByAssocId(ASSOC_TYPE_JOURNAL, $journal->getId(), 3);
			$templateMgr->assign('announcements', $announcements->toArray());
		}

		return false;
	}
}
```

--------------------------------

### Add Stylesheet to HTML Galley

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Assign a stylesheet to the htmlGalley context to inject it into the head of HTML galley files.

```php
$this->addStyle('htmlGalley', 'path/to/galley.css', ['contexts' => 'htmlGalley']);
```

--------------------------------

### Theme Plugin Class Definition

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-setup.html

The main class file for the theme, extending ThemePlugin to register styles and metadata.

```php
<?php
import('lib.pkp.classes.plugins.ThemePlugin');
class TutorialThemePlugin extends ThemePlugin {

    /**
     * Load the custom styles for our theme
     * @return null
     */
    public function init() {
        $this->addStyle('stylesheet', 'styles/index.less');
    }

    /**
     * Get the display name of this theme
     * @return string
     */
    function getDisplayName() {
        return 'Tutorial Theme';
    }

    /**
     * Get the description of this plugin
     * @return string
     */
    function getDescription() {
        return 'An example theme for OJS or OMP built with our amazing documentation.';
    }
}
```

--------------------------------

### Display current publication details

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/publication-versions.html

Use getCurrentPublication() to retrieve and display the most recent version's title and publication date.

```smarty
<h1>
	{$submission->getCurrentPublication()->getLocalizedFullTitle()|escape}
</h1>
<div>
	Published on
	<time>
		{$submission->getCurrentPublication()->getData('datePublished')|date_format:$dateFormatLong}
	</time>
</div>
```

--------------------------------

### Display out-of-date version warning

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/publication-versions.html

Compare the current publication ID with the requested publication ID to identify and warn users about outdated content.

```smarty
{if $currentPublication->getId() !== $publication->getId()}
	<div role="alert">
		You are viewing an old version of this article.
		View the <a href="...">most recent version</a>.
	</div>
{/if}
```

--------------------------------

### setParent()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Sets the current theme as a child of another theme.

```APIDOC
## setParent($themeName)

### Description
Set the current theme to be a Child Theme of another theme.

### Parameters
- **$themeName** (string) - Required - The identifier of the parent theme.
```

--------------------------------

### Modify Parent Theme Styles

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/child-themes.html

Use the modifyStyle method within the init function to compile custom LESS files alongside the parent theme's stylesheet.

```php
	/**
	 * Load the custom styles for our theme
	 * @return null
	 */
	public function init() {
        $this->setParent('defaultthemeplugin');
        $this->modifyStyle('stylesheet', array('addLess' => array('styles/index.less')));
	}
```

--------------------------------

### Modify existing theme options

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Use modifyOptionsConfig to override settings for an existing option defined by a parent theme.

```php
public function init() {
	$this->modifyOptionsConfig('typography', [
		'type' => radio,
		'label' => 'plugins.themes.default.option.typography.label',
		'description' => 'plugins.themes.default.option.typography.description',

		// Replace the existing options with new options.
		'options' => [
			'montserratNotoSerif' => 'plugins.themes.default-child.option.typography.montserratNotoSerif',
			'montserratNotoSans' => 'plugins.themes.default-child.option.typography.montserratNotoSans',
		]
	]);
}
```

--------------------------------

### Remove a theme option

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Use removeOption to completely remove an option from the theme configuration.

```php
public function init() {
	$this->removeOption( 'typography' );
}
```

--------------------------------

### Load scripts in Smarty template

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Use the load_script function in Smarty templates to output scripts for a specific context.

```smarty
{load_script context="frontend" scripts=$scripts}
```

--------------------------------

### Define a LESS variable

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/css-less.html

Use a variable to define a reusable background color for header and footer elements.

```less
@background: red;

.pkp_structure_head,
.pkp_structure_footer {
  background: @background;
}

```

--------------------------------

### Load Stylesheet in Smarty Template

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Use the load_stylesheet function in Smarty templates to output styles assigned to a specific context.

```smarty
{load_stylesheet context="frontend" stylesheets=$stylesheets}
```

--------------------------------

### Access theme options in templates

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Access theme options directly in Smarty templates using the $activeTheme variable.

```smarty
{if $activeTheme->getOption('showDescriptionInJournalIndex')}
	<section>
		{$currentContext->getData('description')}
	</section>
{/if}
```

--------------------------------

### Assign Custom Data to All Templates

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/advanced-custom-data.html

Registers a hook to inject a custom variable into every template loaded by the application.

```php
class DocsThemePlugin extends ThemePlugin {
	/**
	 * Initialize the theme
	 */
	public function init() {
		HookRegistry::register ('TemplateManager::display', array($this, 'loadTemplateData'));
	}

	/**
	 * Fired when the `TemplateManager::display` hook is called.
	 *
	 * @param string $hookname
	 * @param array $args [$templateMgr, $template, $sendContentType, $charset, $output]
	 */
	public function loadTemplateData($hookName, $args) {

		// Retrieve the TemplateManager
		$templateMgr = $args[0];

		// Attach a custom piece of data to the TemplateManager
		$myCustomData = 'This is my custom data. It could be any PHP variable.';
		$templateMgr->assign('myCustomData', $myCustomData);

		return false;
	}
}
```

--------------------------------

### List submissions with current publication

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/publication-versions.html

Iterate through submissions and display the current publication title in lists like tables of contents.

```smarty
<h1>Articles</h1>
{foreach from=$submissions item=$submission}
	<article>
		<h2>
			{$submission->getCurrentPublication()->getLocalizedFullTitle()|escape}
		</h2>
		...
	</article>
{/foreach}
```

--------------------------------

### Register menu areas

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Registers one or more menu areas for navigation menus.

```php
public function init() {
    $this->addMenuArea('primary');
}
```

```php
public function init() {
    $this->addMenuArea(array('primary', 'user'));
}
```

--------------------------------

### Manipulate a field object directly

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Retrieve a specific option's Field object using getOptionConfig to modify its properties.

```php
public function init() {
	$typographyField = $this->getOptionConfig('typography');
	$typographyField->label = __('plugins.themes.default.option.typography.label');
}
```

--------------------------------

### Add a checkbox theme option

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-options-api.html

Registers a checkbox field to enable or disable a specific theme feature.

```php
public function init() {
	$this->addOption('showDescriptionInJournalIndex', 'FieldOptions', [
		'label' => __('manager.setup.contextSummary'),
		'options' => [
			[
				'value' => true,
				'label' => __('plugins.themes.default.option.showDescriptionInJournalIndex.option'),
			],
		],
		'default' => false,
	]);
}
```

--------------------------------

### Reuse variables in LESS

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/css-less.html

Apply the same variable to multiple CSS properties, such as background and border-color.

```less
@background: red;

.pkp_structure_head,
.pkp_structure_footer {
  background: @background;
}

button {
  border-color: @background;
}

```

--------------------------------

### Assign Data to a Specific Template

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/advanced-custom-data.html

Filters the hook to only inject data when a specific template file is being rendered.

```php
class DocsThemePlugin extends ThemePlugin {
	/**
	 * Initialize the theme
	 */
	public function init() {
		HookRegistry::register ('TemplateManager::display', array($this, 'loadTemplateData'));
	}

	/**
	 * Fired when the `TemplateManager::display` hook is called.
	 *
	 * @param string $hookname
	 * @param array $args [$templateMgr, $template, $sendContentType, $charset, $output]
	 */
	public function loadTemplateData($hookName, $args) {

		// Retrieve the TemplateManager and the template filename
		$templateMgr = $args[0];
		$template = $args[1];

		// Don't do anything if we're not loading the right template
		if ($template != 'frontend/pages/article.tpl') {
			return false;
		}

		// Attach the latest 3 announcements if they're enabled for this journal
		$request = Application::get()->getRequest();
		$journal = $request->getJournal();
		if ($journal && $journal->getSetting('enableAnnouncements')) {
			$announcementDao = DAORegistry::getDAO('AnnouncementDAO');
			$announcements =& $announcementDao->getNumAnnouncementsNotExpiredByAssocId(ASSOC_TYPE_JOURNAL, $journal->getId(), 3);
			$templateMgr->assign('announcements', $announcements->toArray());
		}

		return false;
	}
}
```

--------------------------------

### Display specific publication version

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/publication-versions.html

Access the publication variable directly when a user requests a specific version of an article.

```smarty
<h1>
	{$publication->getLocalizedTitle|escape}
</h1>
```

--------------------------------

### Formatting dates in Smarty templates

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/template-variables.html

Use the date_format modifier with configuration variables like $dateFormatShort to reformat machine-readable dates.

```smarty
{$article->getDatePublished()|date_format:$dateFormatShort}
```

--------------------------------

### removeStyle()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Removes a style that has already been registered.

```APIDOC
## removeStyle($name)

### Description
Remove a style that has already been registered, such as a Parent Theme's style.

### Parameters
- **$name** (string) - Required - The name of the style to remove.
```

--------------------------------

### modifyStyle()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Modifies a previously registered style, such as a Parent Theme's style, by updating its arguments.

```APIDOC
## modifyStyle($name, $args)

### Description
Modify the parameters of an existing stylesheet that has already been registered.

### Parameters
- **$name** (string) - Required - The name of the stylesheet to modify.
- **$args** (array) - Optional - Parameters to modify, such as adding additional LESS files.
```

--------------------------------

### Modify a registered script

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Use this method to update parameters of a script that has already been registered, such as one from a parent theme.

```php
/**
 * Modify the params of an existing script
 *
 * @param $name string The name of the script to modify
 * @param $args array Parameters to modify.
 * @see self::addScript()
 * @return null
 */
public function modifyScript($name, $args = array()) { ... }
```

--------------------------------

### removeMenuArea()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Removes a previously registered menu area.

```APIDOC
## removeMenuArea($name)

### Description
Remove a menu area that has already been registered.

### Parameters
- **$name** (string) - Required - The name of the menu area to remove.
```

--------------------------------

### Modify a registered style

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Use modifyStyle to update an existing style, such as adding a LESS file to a parent theme's style.

```php
public function init() {
    $this->modifyStyle('default', array('addLess' => array('styles/colors.less')));
}
```

```php
/**
 * Modify the params of an existing stylesheet
 *
 * @param $name string The name of the stylesheet to modify
 * @param $args array Parameters to modify.
 * @see self::addStyle()
 * @return null
 */
public function modifyStyle($name, $args = array()) { ... }
```

--------------------------------

### removeScript()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Removes a previously registered script.

```APIDOC
## removeScript($name)

### Description
Remove a script that has already been registered, such as a Parent Theme’s script.

### Parameters
- **$name** (string) - Required - The name of the script to remove.
```

--------------------------------

### Escape HTML Content in Smarty

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/security.html

Use the strip_unsafe_html modifier for fields that permit user-entered HTML, such as abstracts or descriptions.

```smarty
{$submission->getLocalizedAbstract()|strip_unsafe_html}
{$issue->getLocalizedDescription()|strip_unsafe_html}
```

--------------------------------

### Override LESS Variables

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/child-themes.html

Define custom LESS variables in the child theme's index.less file to overwrite parent theme defaults.

```less
// Change the default color from blue #007ab2 to red #b21a00
@primary:  #b21a00;
```

--------------------------------

### modifyScript()

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Modifies the parameters of a previously registered script.

```APIDOC
## modifyScript($name, $args)

### Description
Modify a script that has already been registered, such as a Parent Theme’s script. The function accepts an array of $args to override existing script parameters.

### Parameters
- **$name** (string) - Required - The name of the script to modify.
- **$args** (array) - Optional - Parameters to modify.
```

--------------------------------

### Remove a registered style

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Use removeStyle to unregister a style previously added by a parent theme.

```php
public function init() {
    $this->removeStyle('default');
}
```

--------------------------------

### Remove a menu area

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Removes a previously registered menu area.

```php
public function init() {
    $this->removeMenuArea('user');
}
```

--------------------------------

### Escape JavaScript Variables

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/security.html

Use the json_encode modifier when injecting user input into JavaScript to ensure content is treated as a literal string.

```smarty
<script>
	alert({$userMessage|json_encode|default:""});
</script>
```

--------------------------------

### Override Bootstrap LESS Variables

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-bootstrap3.html

Define custom color variables in your child theme's variables.less file to override default Bootstrap styles.

```less
@gray-base:              #012434;
@gray-darker:            lighten(@gray-base, 13.5%);
@gray-dark:              lighten(@gray-base, 20%);
@gray:                   lighten(@gray-base, 33.5%);
@gray-light:             lighten(@gray-base, 46.7%);
@gray-lighter:           lighten(@gray-base, 93.5%);

@brand-primary:         darken(#6f72ed, 6.5%);
@brand-success:         #5cb85c;
@brand-info:            #5bc0de;
@brand-warning:         #f0ad4e;
@brand-danger:          #d9534f;
```

--------------------------------

### Escape Plain Text in Smarty

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/security.html

Use the escape modifier to prevent XSS when displaying user-provided plain text.

```smarty
{$user->getGivenName()}
```

```smarty
{$user->getGivenName()|escape} made a comment.
```

```smarty
{$submission->getLocalizedTitle()|escape}
{$author->getFullName()|escape}
{$issue->getIssueIdentification()|escape}
```

--------------------------------

### Remove a registered script

Source: https://docs.pkp.sfu.ca/pkp-theming-guide/en/theme-api.html

Removes a previously registered script by its name.

```php
public function init() {
    $this->removeScript('default');
}
```
Tokens:
Raw