From 80a3d4a0792839cd811cfc61d58f5c70194f934a Mon Sep 17 00:00:00 2001 From: Tammo ter Hark Date: Mon, 16 Nov 2026 19:51:19 +0100 Subject: [PATCH] feat(variants): thin client themes on one shared code base Architecture: a client theme extends this mother theme via and contains only a generated config.xml + its own files/ (logos). LimeSurvey inherits all views/css/js/images from the mother, so changes here apply to every variant immediately. - variants/.json holds ONLY the house-style values (colors, fonts, font sizes/weights/colors, logo files, logotopmargin, custom fonts). - variants/build.php generates ..//config.xml from the mother config.xml + the json: only those values are replaced, is set, is emptied except . Unknown option keys fail the build loudly, so drift is caught at build time. - Client definitions (variants/.json) are gitignored (see .gitignore) and live in a PRIVATE variants repo or locally; build.php reads them from there via its 2nd argument or RESPONDAGE_VARIANTS_DIR. - README.md: "Client variants" workflow. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe --- .gitignore | 6 ++ README.md | 41 ++++++++ variants/build.php | 226 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 273 insertions(+) create mode 100644 .gitignore create mode 100644 variants/build.php diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b299d56 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +# Client variant definitions contain confidential house-style values (client +# names, colors, fonts, logo files). They are NOT kept in this public repo: +# store them in the private variants repository or locally, and point +# variants/build.php at that folder (2nd CLI argument or RESPONDAGE_VARIANTS_DIR). +variants/*.json +variants/README.internal.md diff --git a/README.md b/README.md index bcb2913..7417087 100644 --- a/README.md +++ b/README.md @@ -75,3 +75,44 @@ its own font files and css: loaded by the variant's own css). 4. Run `php variants/build.php ` and upload/reset as usual. +## Client variants (house styles) without code duplication + +House-style-specific values are ONLY: colors, fonts, and font +sizes/colors/weights (plus logo files). Everything else lives once, here. + +Workflow: + +1. In `config.xml`, the house-style options are marked with `HOUSE-STYLE` + comments (colors, fonts, font sizes/weights, logo files, logo top margin, + background image/color). Only those values belong in a variant json — + never hardcode house-style values in shared files (`views/`, `sass/`, + `css/`, `scripts/`), because those are inherited by all variants. +2. Create `variants/.json` with the variant name/title/description and + only the house-style option keys with the client values: + ```json + { + "name": "client_vanilla", + "title": "Client Vanilla", + "options": { "primarycolor": "#123456", "fontsize": "18px" } + } + ``` +2. Run `php variants/build.php `. This generates + `..//config.xml`: a copy of this theme's config.xml with only those + option values replaced, `` set to this theme, and the `` + section emptied except `` (same as LimeSurvey's own "extend + theme" action), so engine settings are inherited. The `` list is + kept: LimeSurvey resolves each listed file in the variant first and then in + the mother, so the mother's css/js keep loading until a variant ships its + own file with the same name. Unknown option keys make the build fail + loudly, so drift is caught at build time. +3. Put the client's images in `..//files/`, upload the folder to + `upload/themes/survey/`, install/reset the theme in LimeSurvey. + +Because of the native `` mechanism: +- changes to any file (twig/css/js) in this mother theme apply to all + variants immediately — edit them only here; +- changes to non-house-style option defaults in `config.xml` apply to a + variant after re-running the build script and resetting that variant theme; +- house-style values live only in `variants/.json` and the variant's + `files/`, so they are never overwritten by changes in this mother theme. + diff --git a/variants/build.php b/variants/build.php new file mode 100644 index 0000000..145697e --- /dev/null +++ b/variants/build.php @@ -0,0 +1,226 @@ + in its config.xml). LimeSurvey then inherits ALL files + * (views, css, js, images, options page) from the mother theme, so any + * change made here in a file automatically applies to every variant. + * + * Only config.xml is generated per variant: it is a copy of this mother + * config.xml in which ONLY the house-style option values (colors, fonts, + * font sizes/colors/weights, logo files) listed in variants/.json + * are replaced, plus the metadata (name/title/description/extends). + * The section is emptied except , so engine settings + * (css framework, packages, view/files directories, template editor) are + * inherited from the mother. The section is kept as-is: LimeSurvey + * resolves each listed file in the variant first and then in the mother, + * so the mother's css/js keep loading until the variant ships its own file + * with the same name (which then replaces the mother's file). This mirrors + * what LimeSurvey itself does when you "extend" a theme in the theme editor. + * + * Usage: + * php variants/build.php [definitions-dir] + * + * The definitions (variants/.json) contain confidential client + * house-style values and are NOT kept in this (public) repository - see + * .gitignore. Store them in the private variants repository or locally, and + * point this script at that folder via the optional second argument or the + * RESPONDAGE_VARIANTS_DIR environment variable. + * + * Example: + * php variants/build.php /path/to/private-variants + * + * Optional keys in the variant json: + * "files_add": {"css": ["css/variant.css"], "js": []} extra files shipped by the + * variant, appended to the list of the generated config.xml + * "fontOptions": [{"value": "my_custom_font", "label": "My Custom Font"}] custom fonts, + * appended to the "Custom (this theme)" optgroup of the font dropdown + * + * Output: + * ..//config.xml (next to this theme, in upload/themes/survey) + * + * After running this script, upload the variant folder to + * upload/themes/survey/ and (re)install or reset the theme in LimeSurvey + * (Theme options -> reset), so the new config.xml is imported into the DB. + * + * If an option key in the json no longer exists in the mother config.xml, + * the script fails loudly, so drift between mother and variant is caught + * at build time instead of silently rendering wrong values. + */ + +if (PHP_SAPI !== 'cli') { + fwrite(STDERR, "This script must be run from the command line.\n"); + exit(1); +} + +$variantName = isset($argv[1]) ? trim($argv[1]) : ''; +if ($variantName === '' || !preg_match('/^[a-z0-9_]+$/i', $variantName)) { + fwrite(STDERR, "Usage: php variants/build.php [definitions-dir]\n"); + fwrite(STDERR, " must match an existing /.json file.\n"); + fwrite(STDERR, " Default definitions-dir: the variants/ folder next to this script, or RESPONDAGE_VARIANTS_DIR.\n"); + exit(1); +} + +$motherDir = dirname(__DIR__); // .../themes/survey/respondage_vanilla +$themesDir = dirname($motherDir); // .../themes/survey +$motherConfig = $motherDir . DIRECTORY_SEPARATOR . 'config.xml'; +$definitionsDir = $argv[2] ?? (getenv('RESPONDAGE_VARIANTS_DIR') ?: __DIR__); +$definitionFile = rtrim($definitionsDir, '/\\') . DIRECTORY_SEPARATOR . $variantName . '.json'; + +foreach ([$motherConfig, $definitionFile] as $f) { + if (!is_file($f)) { + fwrite(STDERR, "Required file not found: $f\n"); + exit(1); + } +} + +$definition = json_decode(file_get_contents($definitionFile), true); +if (!is_array($definition)) { + fwrite(STDERR, "Invalid JSON in $definitionFile\n"); + exit(1); +} + +$doc = new DOMDocument(); +$doc->preserveWhiteSpace = false; +$doc->formatOutput = true; +if (!$doc->load($motherConfig)) { + fwrite(STDERR, "Could not parse mother config: $motherConfig\n"); + exit(1); +} +$xpath = new DOMXPath($doc); + +$motherName = (string) $xpath->query('//metadata/name')->item(0)->textContent; + +// --- metadata: identify the variant, point extends to the mother theme --- +function setMetadata(DOMXPath $xpath, DOMDocument $doc, string $tag, string $value): void +{ + $node = $xpath->query("//metadata/$tag")->item(0); + if ($node === null) { + $node = $doc->createElement($tag); + $xpath->query('//metadata')->item(0)->appendChild($node); + } + $node->textContent = $value; +} + +setMetadata($xpath, $doc, 'name', $definition['name'] ?? $variantName); +setMetadata($xpath, $doc, 'title', $definition['title'] ?? ucfirst($variantName)); +if (isset($definition['description'])) { + setMetadata($xpath, $doc, 'description', $definition['description']); +} +setMetadata($xpath, $doc, 'extends', $motherName); +setMetadata($xpath, $doc, 'lastUpdate', date('Y-m-d H:i:s')); + +// --- empty the section except : inherited from the mother --- +// (same as TemplateManifest::deleteEngineInDom() does when extending a theme in LimeSurvey) +$engineNode = $xpath->query('//engine')->item(0); +if ($engineNode !== null) { + foreach (iterator_to_array($engineNode->childNodes) as $child) { + if ($child instanceof DOMElement && $child->nodeName !== 'optionspage') { + $engineNode->removeChild($child); + } elseif ($child instanceof DOMComment) { + $engineNode->removeChild($child); + } + } +} + +// --- extra files shipped by the variant itself --- +// In the variant json: "files_add": {"css": ["css/variant.css"], "js": []} +// They are appended to the list. The mother's files keep loading until the +// variant ships a file with the same name; from that moment it replaces the mother's +// file (LimeSurvey "add" also means "replace" for identical paths). +if (!empty($definition['files_add'])) { + $filesNode = $xpath->query('//files')->item(0); + if ($filesNode === null) { + fwrite(STDERR, "No section found in mother config\n"); + exit(1); + } + foreach (['css', 'js', 'print_css'] as $type) { + $values = $definition['files_add'][$type] ?? []; + if (empty($values)) { + continue; + } + $typeNode = $xpath->query('//files/' . $type)->item(0); + if ($typeNode === null) { + $typeNode = $doc->createElement($type); + $filesNode->appendChild($typeNode); + } + foreach ((array) $values as $file) { + $add = $doc->createElement('add'); + $add->appendChild($doc->createTextNode((string) $file)); + $typeNode->appendChild($add); + } + } +} + +// --- custom fonts of the variant, added to the font dropdown --- +// In the variant json: "fontOptions": [{"value": "my_custom_font", "label": "My Custom Font"}] +// The font files themselves live in the variant's files/fonts/ and the @font-face + +// body.font- rule in a css file shipped by the variant (see files_add, e.g. +// css/variant.css with src: url('../files/fonts/my-custom-font.woff2')). +// data-font-package stays "websafe": LimeSurvey only knows the core font packages +// (application/config/fonts.php), and "websafe" is the neutral one, so no missing +// package is requested. The real font is loaded by the variant's own css. +if (!empty($definition['fontOptions'])) { + $optgroup = $xpath->query('//options/font/dropdownoptions/optgroup[@label="Custom (this theme)"]')->item(0); + if ($optgroup === null) { + fwrite(STDERR, "No found in the font dropdown of the mother config.xml\n"); + exit(1); + } + foreach ((array) $definition['fontOptions'] as $font) { + if (empty($font['value']) || empty($font['label'])) { + fwrite(STDERR, "Each entry in 'fontOptions' needs 'value' and 'label'\n"); + exit(1); + } + $value = preg_replace('/[^a-z0-9_]/i', '_', (string) $font['value']); + $option = $doc->createElement('option'); + $option->setAttribute('class', 'font-' . $value); + $option->setAttribute('value', $value); + $option->setAttribute('data-font-package', 'websafe'); + $option->appendChild($doc->createTextNode((string) $font['label'])); + $optgroup->appendChild($option); + } +} + +// --- options: replace only the house-style values listed in the json --- +if (!empty($definition['options']) && !is_array($definition['options'])) { + fwrite(STDERR, "'options' in $definitionFile must be an object of optionName => value\n"); + exit(1); +} +$optionsNode = $xpath->query('//options')->item(0); +if ($optionsNode === null) { + fwrite(STDERR, "No section found in mother config\n"); + exit(1); +} +foreach (($definition['options'] ?? []) as $key => $value) { + $matches = $xpath->query('//options/' . $key); + if ($matches->length === 0) { + fwrite(STDERR, "Option '$key' from $definitionFile does not exist in the mother config.xml.\n"); + fwrite(STDERR, "Remove it from the json or rename it there; the mother theme changed.\n"); + exit(1); + } + $option = $matches->item(0); + // Replace only the text value, keep child elements (e.g. of the font option) + foreach (iterator_to_array($option->childNodes) as $child) { + if ($child instanceof DOMText) { + $option->removeChild($child); + } + } + $option->insertBefore($doc->createTextNode((string) $value), $option->firstChild); +} + +// --- write the variant config --- +$variantDir = $themesDir . DIRECTORY_SEPARATOR . $variantName; +if (!is_dir($variantDir) && !mkdir($variantDir, 0775, true)) { + fwrite(STDERR, "Could not create directory: $variantDir\n"); + exit(1); +} +if (!is_dir($variantDir . DIRECTORY_SEPARATOR . 'files')) { + mkdir($variantDir . DIRECTORY_SEPARATOR . 'files', 0775, true); +} +$out = $variantDir . DIRECTORY_SEPARATOR . 'config.xml'; +$doc->save($out); + +echo "Variant '$variantName' built: $out\n"; +echo 'Options overridden: ' . (empty($definition['options']) ? '(none)' : implode(', ', array_keys($definition['options']))) . "\n"; +echo "Remember: upload the folder to upload/themes/survey/ and reset the theme in LimeSurvey.\n";