Search by

therealworld / theme-module

therealworld

Help to configure OXID7 childthemes correctly.

Package info

bitbucket.org/therealworld/theme-module

Homepage

Issues

Type:oxideshop-module

pkg:composer/therealworld/theme-module

Statistics

Installs: 889

Dependents: 0

Suggesters: 0

v3.0.20 2026-11-02 07:42 UTC

README

Deutsche Fassung: README.de.md

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

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

GroupOption (admin label)SettingDefaultEffect
Template debugEnable Twig debug modebTRWThemeActivateDebugoffTwig 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 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.
  • Class extensions: ArticleListController, SearchController, ManufacturerListController and VendorListController (…\Application\Controller\*) each use the trait …\Application\Traits\ThemeListDisplayType, which overrides getListDisplayType(); the types come from …\Core\ThemeListDisplayTypes (constraint of sDefaultListDisplayType of theme:<active theme>, cached per request). One extension per controller is needed: a FrontendController extension would not reach them, because OXID builds the chain for the class oxNew() creates.
  • No own database tables, no migrations.
  • No frontend assets (CSS/JS) and no resources/ build.