README

vendor-logo the-real-world.de

description

A child theme in OXID starts without the settings of its parent theme, and the stock admin offers no way to add, rename or regroup theme options. This module adds an admin page that fills that gap:

copy the parent theme's options into the active child theme (insert only, nothing is overwritten)
create, edit, rename and delete theme options, edit the values of select options, rename option groups
export the options of any theme as YAML and import them into another theme
widen the database columns for option names from 100 to 255 characters
switch Twig into debug mode for template development
Composer package: therealworld/theme-module
OXID module id: trwtheme

Requirements and installation

OXID eShop CE >= 7.4, PHP ^8.3
therealworld/tools-plugin >= 3.2 (installed automatically)

composer require therealworld/theme-module
vendor/bin/oe-console oe:module:install vendor/therealworld/theme-module
vendor/bin/oe-console oe:module:activate trwtheme

With therealworld/clirun-plugin installed, vendor/bin/oe-console trw:module:setup trwtheme does both steps in one go.

On every activation the module checks the two option-name columns (oxconfig.oxvarname, oxconfigdisplay.oxcfgvarname) and repairs their definition if an earlier length switch left them nullable or without default and comment.

Configuration

Extensions → Modules → the-real-world - ChildTheme Configurator → Settings

Group	Option (admin label)	Setting	Default	Effect
Template debug	Enable Twig debug mode	`bTRWThemeActivateDebug`	off	Twig runs in debug mode: template errors come with a stack trace and `dump()` works. Has no effect while the shop is in productive mode.

Admin page

Extensions → ChildTheme Configurator. The page always works on the theme that is active in the current shop.

Always available:

Overview – active theme and its parent theme. If the active theme is not a child theme, a warning is shown and the option editing forms are hidden.
Parenttheme-Options → assume (child themes only) – adds the parent theme's options that the child theme does not have yet. Options that already exist keep their value, type, group and selectable values.
OXID Optionlength – switches the option-name columns between 100 (OXID default) and 255 characters. Shrinking back to 100 is refused while a stored name is longer.
Export Theme – downloads the options of the selected theme as <theme-id>.yaml.
Import Theme – uploads such a YAML file and writes its options into the theme whose id is entered as target.

Only for child themes:

Edit Theme Option – change name, group and type of an option. Value, selectable values and position are kept.
Edit Theme Option of Type "Select" – edit the selectable values of a select option, separated by | (e.g. contact|list|detail). An empty field saves nothing.
Rename Theme-Option-Gruppen-ID – give an option group a new id.
Delete Theme option(s) – delete a single option of the active theme, or all options of a selected theme. The link Delete All Options from All Themes (with a confirmation prompt) deletes the options of every installed theme in the current shop.
create new Childtheme-Option – new option with group (existing or new), name and type (Boolean, String, Array, Associative Array, Select-List). An option that already exists is not overwritten; use "Edit Theme Option" instead.

After a new or renamed option or group the page reminds you that admin language constants may be needed: SHOP_THEME_GROUP_<group> for the group and SHOP_THEME_<name> for the option, in the theme's admin language files.

Caveats

Deleting options, importing into an existing theme and shrinking the column length change configuration data directly. Export the theme first if in doubt.

For developers

Admin controller: TheRealWorld\ThemeModule\Application\Controller\Admin\ThemeController (controller key themecontroller, lowercase as in menu.xml; template @trwtheme/admin/themeconfig, menu entry mxtrwtheme under mxextensions). The forms post to its run* methods via fnc; the "all themes" link calls runDeleteAllOptions.
Option handling is done by TheRealWorld\ToolsPlugin\Core\ToolsTheme (getThemeOptions(), setThemeOptions(), deleteThemeOptions(), deleteAllThemeOptions(), getOptionGroups()) and ToolsConfig (select constraints, group rename); YAML via ToolsYaml.
TheRealWorld\ThemeModule\Core\ThemeOptionColumns::ensure() asserts the definition of the two option-name columns (length, NOT NULL, default '', comment, current charset kept). Called from ThemeEvents::onActivate() and on every length switch; deliberately not a migration because the length is switched at runtime.
ThemeEvents::onActivate() also sorts the class extension chain by module dependencies (ClassExtensionChainService::sortExtensionsByDependencyChain()).
DI decorator: TheRealWorld\ThemeModule\Decorator\TwigContextDecorator decorates OxidEsales\Twig\TwigContextInterface and returns the debug flag from ThemeConfig::isActivateThemeDebug() (never in productive mode).
metadata.php also declares two settings without a group, sAdminTheme and sAdminCustomTheme; they are not shown in the admin and not read by the module.
No class extensions, no own database tables, no migrations.
No frontend assets (CSS/JS) and no resources/ build.

therealworld / theme-module

Package info

Security

Statistics