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. * * Standard layout in that definitions dir per client: * .json house-style option values + fontOptions + files_add * /files/... client assets (logos, fonts in files/fonts/) * /css/... client css (e.g. css/variant.css with @font-face) * The / folder is copied into the generated theme automatically. * * 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; } /** Recursively copy a directory (used for the variant's own assets). */ function copyDirRecursive(string $src, string $dst): void { if (!is_dir($dst)) { mkdir($dst, 0775, true); } $dir = opendir($src); while (($entry = readdir($dir)) !== false) { if ($entry === '.' || $entry === '..') { continue; } $s = $src . DIRECTORY_SEPARATOR . $entry; $d = $dst . DIRECTORY_SEPARATOR . $entry; if (is_dir($s)) { copyDirRecursive($s, $d); } else { copy($s, $d); } } closedir($dir); } 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); // --- copy the variant's own assets (fonts, css, images) from the definitions dir --- // Standard layout in the private variants repo: // // with e.g. files/fonts/*.woff2, files/*.png, css/variant.css. Everything in that // folder is copied into the generated theme, so a client-specific font or css is // part of the variant by default (no manual copying needed). $variantAssets = rtrim($definitionsDir, '/\\') . DIRECTORY_SEPARATOR . $variantName; if (is_dir($variantAssets)) { copyDirRecursive($variantAssets, $variantDir); echo "Copied variant assets: $variantAssets -> $variantDir\n"; } 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";