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>
226 lines
10 KiB
PHP
226 lines
10 KiB
PHP
<?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";
|