respondage_vanilla/README.md
Tammo ter Hark 0ca0da8b1a feat: public release export of the mother theme only
- variants/export_public.sh builds a public folder + zip of ONLY this mother
  theme: excludes .git and variants/*.json (client house-style definitions),
  scans the result for client-identifying strings and aborts on any hit.
  Default output: <limesurvey-root>/dist (not inside upload/themes/survey,
  which is scanned for themes).
- README.md: "Public release" section; client-identifying examples scrubbed
  (generic <client> placeholders, no client names/colors); note that client
  definitions live in a private repo (gitignored here).
- .gitignore keeps variants/*.json (and the internal variants README) out of
  this public repository.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-16 19:51:19 +01:00

6.3 KiB

Respondage Vanilla — LimeSurvey theme (version 6/7 compatible), extension of the core Vanilla theme.

This is the MOTHER theme. Client-specific variants (e.g. <client>_vanilla) extend this theme via <extends>respondage_vanilla</extends> and contain only a generated config.xml plus their own files/ (logos). LimeSurvey inherits all files (views, css, js, images, options page) from the mother theme, so any change to a file in this theme automatically applies to all variants — no copying of files needed.

What's in here

  • config.xml — theme manifest incl. all theme options (colors, fonts, font sizes/weights/colors, header logos, ...).
  • views/ — twig overrides (header with left/center/right logos and navbar menu color, survey list, question, group description).
  • sass/ → css/plain.css — theme styles (keep both in sync; plain.css is the compiled output of sass/plain.sass).
  • css/custom.css, scripts/custom.js — loaded last, safe for project tweaks.
  • options/ — options page assets.
  • variants/ — build/export tooling only. Client variant definitions (variants/*.json) hold confidential house-style values, are gitignored (see .gitignore) and live in the private variants repo, not here.

Header logos (left / center / right)

Three independent logo options in the Images category: brandlogo(+brandlogofile) left, centerlogo(+centerlogofile) center, rightlogo(+rightlogofile) right. The center logo is absolutely centered in the navbar (see sass/plain.sass). Logo files are looked up in the theme's own files/ folder first, then in the mother theme's files/ folder.

Menu item color in the top bar

Option navbarfontcolor (Colors category) sets the text color of the menu items in the navbar; it is applied in views/subviews/header/custom_header.twig and should contrast with headerbackgroundcolor.

Distance from the logo to the top of the screen

Option logotopmargin (Images category, e.g. 15px or 0px) sets the top padding of the header logos, applied in custom_header.twig. Use 0px to align a logo exactly with the top of the screen.

Custom fonts per variant

LimeSurvey only knows its core font packages (application/config/fonts.php), so a theme cannot register a font-* package itself. Instead a variant ships its own font files and css:

  1. Put the font files in the variant's files/fonts/ (e.g. my-custom-font.woff2).
  2. Create css/variant.css in the variant with the @font-face and the body class rule (the selected font is applied as font-<value> on <body>):
    @font-face {
        font-family: 'My Custom Font';
        src: url('../files/fonts/my-custom-font.woff2') format('woff2');
        font-weight: 400; font-style: normal;
    }
    body.font-my_custom_font {
        font-family: 'My Custom Font', Arial, sans-serif;
    }
    
    (../files/... works because the asset manager copies the whole theme dir.)
  3. In variants/<client>.json declare the css file and the dropdown entry:
    {
        "files_add": { "css": ["css/variant.css"], "js": [] },
        "fontOptions": [ { "value": "my_custom_font", "label": "My Custom Font" } ]
    }
    
    build.php appends the css to the <files> list and the font to the "Custom (this theme)" optgroup of the font dropdown (data-font-package stays websafe, so no nonexistent package is requested — the real font is 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:
    {
        "name": "client_vanilla",
        "title": "Client Vanilla",
        "options": { "primarycolor": "#123456", "fontsize": "18px" }
    }
    
  3. 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.
  4. 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.

Public release

The public version of this theme is ONLY the mother theme: this directory without variants/ (client house-style definitions) and without .git. Build it with:

bash variants/export_public.sh [output-dir]

This creates a checked, client-free copy plus a zip (default output: <limesurvey-root>/dist/). Publish only that artifact / the main branch. NEVER publish: variants/*.json, generated client theme folders, or any git branch containing a client theme (client names, colors and logos are confidential). Client variant definitions stay in a PRIVATE repository (or locally); variants/*.json is gitignored and build.php reads the definitions from that private folder via its second argument or RESPONDAGE_VARIANTS_DIR.