Theme preferences

Theme preferences are admin-editable values that belong to the theme rather than to any plugin — section headings, subtitles, layout switches, feature toggles. They are edited under Admin → Theme → Aragorn → Configure and read in layout templates through the {THEME_PREF} shortcode.

Use a theme preference when the value is chrome: a single string or setting that shapes how a section is presented. Use Featurebox, Custom Pages or News when the value is content: repeatable, ordered, or authored over time.

Preferences are stored in their own row of the core table (theme_aragorn), not in the site-wide pref blob. Uninstalling or switching the theme leaves them untouched.

---

Adding a preference

1. Declare the field

Add an entry to config() in theme_config.php. The array key is the pref name you will use in templates.

public function config()
{
    return array(

        'features_subtitle' => array(
            'title'      => defset('LAN_THEME_PREF_FEATURES_SUBTITLE', 'Features: subtitle'),
            'type'       => 'text',
            'multilan'   => true,
            'writeParms' => array(
                'size'      => 'xxlarge',
                'maxlength' => 250,
            ),
            'help'       => defset('LAN_THEME_PREF_FEATURES_SUBTITLE_HELP', 'Short line shown under the Features heading.'),
        ),

    );
}

Each field array is passed straight to e_form::renderElement(), so any field type and write parameter that works in a plugin admin UI works here too.

Key	Purpose
title	Label in the left column of the config table. Required.
type	text, textarea, dropdown, boolean, image, method, …
multilan	true stores one value per language. See below.
writeParms	Passed to the form element — size, maxlength, optArray, default, post, …
help	Help text rendered under the field.

2. Add the label to the admin language file

e107_themes/aragorn/languages/English_admin.php

define('LAN_THEME_PREF_FEATURES_SUBTITLE', 'Features: subtitle');
define('LAN_THEME_PREF_FEATURES_SUBTITLE_HELP', 'Short line shown under the Features heading.');

Front-end strings stay in languages/English.php. The two files are loaded by different code paths and neither one implies the other.

Why the split, and why e107::themeLan('admin', basename(__DIR__), true) instead of e107::lan('theme', 'admin', true)? Core themes use the short form, but it resolves through the THEME constant, which points to the admin theme while you are in the admin area. That works for bootstrap3 only because it doubles as the default admin theme. A front-end-only theme has to name itself explicitly.

3. Use it

Nothing else is required — no install step, no upgrade routine. A pref that has never been saved simply reads as empty.

---

Using a preference in a layout

<!-- short form -->
{THEME_PREF=features_subtitle}

<!-- with a fallback for the not-yet-configured case -->
{THEME_PREF: name=features_subtitle&default=What we offer}

<!-- inside an HTML attribute -->
<section aria-label="{THEME_PREF: name=features_subtitle&filter=attribute}">

<!-- plain text, tags stripped -->
<meta name="description" content="{THEME_PREF: name=features_subtitle&filter=text}">

A typical section:

<div class="container-xl py-5">
    <div class="text-center mb-4">
        <h2 class="section-title">{THEME_PREF: name=features_title&default=Features}</h2>
        <p class="section-subtitle text-secondary">{THEME_PREF: name=features_subtitle&default=What we offer}</p>
    </div>

    {FEATUREBOX|category=features}
</div>

Parameters

Parameter	Default	Description
name	—	Pref key as declared in config(). Required.
default	empty	Returned when the pref is unset or empty for the current language.
filter	html	Output context — see below.

filter	Output
html	Bbcode and constants parsed, emotes and auto-linking off (e_parse TITLE context).
text	Tags stripped, plain text.
attribute	Escaped for use inside an HTML attribute.

The short form {THEME_PREF=key} accepts only the pref name. Any parameter means the colon form {THEME_PREF: a=b&c=d} — that is the only syntax e107 parses into an array.

From PHP

$subtitle = e107::getScBatch('theme')->sc_theme_pref(array(
    'name'    => 'features_subtitle',
    'default' => 'What we offer',
));

Or read the raw value, bypassing the parser — in which case escape it yourself:

$value = e107::getThemePref('features_subtitle');

---

Multilingual fields

With 'multilan' => true the value is stored as array(e_LANGUAGE => value). The language currently selected in the admin area is the one being edited, so switching admin language and saving again adds a second translation rather than overwriting the first.

{THEME_PREF} resolves the active front-end language automatically. A language with no value saved yet falls through to default=.

Multilan is worth it for anything a visitor reads. Skip it for switches, class names and other values that are the same in every language.

---

Notes and gotchas

An empty pref does not remove its wrapper. {THEME_PREF} returns an empty string, but the surrounding <p> stays in the markup. Either supply a sensible default=, or give the section its own shortcode that returns the wrapper too.

+ in default= becomes a space. The colon syntax is parsed with parse_str(). Write %2B for a literal plus. Spaces themselves are fine.

& vs & — both work. e107 normalises the entity before parsing parameters.

Constants as values. A stored value shorter than 35 characters that matches the name of a defined constant is replaced by that constant's value. This makes LAN_THEME_FEATURES_SUB a valid thing to type into the field, but it also means a subtitle that happens to read SITENAME will not survive verbatim.

Escaping is not optional. e107 does not run theme preferences through toDB() on save — the posted value is written to the pref object as-is. Anyone with the TMP admin permission can therefore store raw markup. Always output through {THEME_PREF} or $tp, never echo the raw pref.

No init() in the theme shortcode batch. e107 skips init() for theme_shortcodes specifically, so the plugin pattern of caching prefs there silently does nothing. {THEME_PREF} reads per call instead; the pref object is already loaded, so there is no extra query.