feat(variants): thin client themes on one shared code base

Architecture: a client theme extends this mother theme via <extends> 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/<client>.json holds ONLY the house-style values (colors, fonts,
  font sizes/weights/colors, logo files, logotopmargin, custom fonts).
- variants/build.php generates ../<client>/config.xml from the mother
  config.xml + the json: only those values are replaced, <extends> is set,
  <engine> is emptied except <optionspage>. Unknown option keys fail the
  build loudly, so drift is caught at build time.
- Client definitions (variants/<client>.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 <vibe@mistral.ai>
This commit is contained in:
Tammo ter Hark 2026-11-16 19:51:19 +01:00
commit 80a3d4a079
3 changed files with 273 additions and 0 deletions

6
.gitignore vendored Normal file
View file

@ -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

View file

@ -75,3 +75,44 @@ its own font files and css:
loaded by the variant's own css).
4. Run `php variants/build.php <client>` 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/<client>.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 <client>`. This generates
`../<client>/config.xml`: a copy of this theme's config.xml with only those
option values replaced, `<extends>` set to this theme, and the `<engine>`
section emptied except `<optionspage>` (same as LimeSurvey's own "extend
theme" action), so engine settings are inherited. The `<files>` 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 `../<client>/files/`, upload the folder to
`upload/themes/survey/`, install/reset the theme in LimeSurvey.
Because of the native `<extends>` 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/<client>.json` and the variant's
`files/`, so they are never overwritten by changes in this mother theme.

226
variants/build.php Normal file
View file

@ -0,0 +1,226 @@
<?php
/**
* Build a thin client variant of this theme (respondage_vanilla).
*
* A variant is a separate LimeSurvey theme that extends this mother theme
* (<extends> 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/<name>.json
* are replaced, plus the metadata (name/title/description/extends).
* The <engine> section is emptied except <optionspage>, so engine settings
* (css framework, packages, view/files directories, template editor) are
* inherited from the mother. The <files> 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 <variantName> [definitions-dir]
*
* The definitions (variants/<variantName>.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 <client> /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 <files> 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:
* ../<variantName>/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 <variantName> [definitions-dir]\n");
fwrite(STDERR, " <variantName> must match an existing <definitions-dir>/<variantName>.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 <engine> section except <optionspage>: 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 <files> 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 <files> 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-<value> 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 <optgroup label=\"Custom (this theme)\"> 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 <options> 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. <dropdownoptions> 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";