The definitions dir (private variants repo) now has a standard layout per client: <client>.json + <client>/files/... + <client>/css/variant.css. build.php copies <client>/ into the generated theme folder, so a client-specific font or css is part of the variant by default. README updated accordingly. Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
6.7 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:
- Put the font files in the client folder of the PRIVATE variants repo:
<client>_vanilla/files/fonts/(e.g.my-custom-font.woff2). This folder is standard per client and is copied into the generated theme automatically bybuild.php(together with e.g.files/*.pnglogos andcss/variant.css). - Create
css/variant.cssin that same client folder with the@font-faceand the body class rule (the selected font is applied asfont-<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.) - In
variants/<client>.jsondeclare the css file and the dropdown entry:{ "files_add": { "css": ["css/variant.css"], "js": [] }, "fontOptions": [ { "value": "my_custom_font", "label": "My Custom Font" } ] }build.phpappends the css to the<files>list and the font to the "Custom (this theme)" optgroup of the font dropdown (data-font-packagestayswebsafe, so no nonexistent package is requested — the real font is loaded by the variant's own css). - Run
php variants/build.php <client> <definitions-dir>(or set RESPONDAGE_VARIANTS_DIR) and upload/reset as usual. The<client>/assets folder from the definitions dir is copied into../<client>/automatically.
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:
- In
config.xml, the house-style options are marked withHOUSE-STYLEcomments (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. - Create
variants/<client>.jsonwith 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" } } - 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. - Put the client's images in
../<client>/files/, upload the folder toupload/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.xmlapply to a variant after re-running the build script and resetting that variant theme; - house-style values live only in
variants/<client>.jsonand the variant'sfiles/, 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.