therealworld / theme-module
Help to configure OXID7 childthemes correctly.
Package info
bitbucket.org/therealworld/theme-module
Type:oxideshop-module
pkg:composer/therealworld/theme-module
Requires
- php: ^8.3
- oxid-esales/oxideshop-ce: >=v7.4
- therealworld/tools-plugin: >=v3.2
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- v3.x-dev
- v3.0.20
- v3.0.19
- v3.0.18
- v3.0.17
- v3.0.16
- v3.0.15
- v3.0.14
- v3.0.13
- v3.0.12
- v3.0.11
- v3.0.10
- v3.0.9
- v3.0.8
- v3.0.7
- v3.0.6
- v3.0.5
- v3.0.4
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v2.0.14
- v2.0.13
- v2.0.12
- v2.0.11
- v2.0.10
- v2.0.9
- v2.0.8
- v2.0.7
- v2.0.6
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.8.2
- v1.8.1
- v1.8.0
- v1.7.4
- v1.7.3
- v1.7.2
- v1.7.1
- v1.7.0
- v1.6.13
- v1.6.12
- v1.6.11
- v1.6.10
- v1.6.9
- v1.6.8
- v1.6.7
- v1.6.6
- v1.6.5
- v1.6.4
- v1.6.3
- v1.6.2
- v1.6.1
- v1.6.0
- v1.5.3
- v1.5.2
- v1.5.1
- v1.5.0
- v1.4.2
- v1.4.1
- v1.4.0
- dev-master
This package is auto-updated.
Last update: 2026-11-02 07:43:42 UTC
README
Deutsche Fassung: README.de.md

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
In the frontend it keeps article lists to the list display types the active theme can render (see Frontend).
- 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.
Frontend
List display type (ldtype) limited to the active theme. The core accepts the types
grid, line and infogrid and falls back to infogrid for every unknown value. Apex and
its child themes have no infogrid template, so a list opened with ldtype=infogrid (old
Flow/Wave links, often still indexed in migrated shops) or with any made-up value
(bots) wrote one "template not found" error with a full stack trace per article box into
the shop log.
The module takes the allowed types from the choices of the active theme's option
sDefaultListDisplayType (Apex: line|grid; a Flow-based theme keeps infogrid). An unknown
type falls back to the configured sDefaultListDisplayType, then to the first type of the
theme; the corrected value is what goes into the session. If the theme has no such option,
the core's list applies. Covered are category, search, manufacturer and vendor lists.
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 keythemecontroller, lowercase as inmenu.xml; template@trwtheme/admin/themeconfig, menu entrymxtrwthemeundermxextensions). The forms post to itsrun*methods viafnc; the "all themes" link callsrunDeleteAllOptions. - Option handling is done by
TheRealWorld\ToolsPlugin\Core\ToolsTheme(getThemeOptions(),setThemeOptions(),deleteThemeOptions(),deleteAllThemeOptions(),getOptionGroups()) andToolsConfig(select constraints, group rename); YAML viaToolsYaml. TheRealWorld\ThemeModule\Core\ThemeOptionColumns::ensure()asserts the definition of the two option-name columns (length,NOT NULL, default'', comment, current charset kept). Called fromThemeEvents::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\TwigContextDecoratordecoratesOxidEsales\Twig\TwigContextInterfaceand returns the debug flag fromThemeConfig::isActivateThemeDebug()(never in productive mode). metadata.phpalso declares two settings without a group,sAdminThemeandsAdminCustomTheme; they are not shown in the admin and not read by the module.- Class extensions:
ArticleListController,SearchController,ManufacturerListControllerandVendorListController(…\Application\Controller\*) each use the trait…\Application\Traits\ThemeListDisplayType, which overridesgetListDisplayType(); the types come from…\Core\ThemeListDisplayTypes(constraint ofsDefaultListDisplayTypeoftheme:<active theme>, cached per request). One extension per controller is needed: aFrontendControllerextension would not reach them, because OXID builds the chain for the classoxNew()creates. - No own database tables, no migrations.
- No frontend assets (CSS/JS) and no
resources/build.