Create your own client theme
This guide builds a client area theme of your own, from a copy of Palisade to the moment your
clients see it. For a few small changes, a template in html_custom
or Custom CSS is less work: an update
keeps those too, and you keep getting Palisade’s fixes.
What a theme is
Section titled “What a theme is”A theme is a folder in themes/. Palisade, as a release installs it:
| Path | What it holds |
|---|---|
manifest.json |
The theme’s name, version, author and Markdown classes. |
html/ |
The Twig templates. |
html_custom/ |
Optional. A template here wins over the one with the same name in html/. |
config/settings.html.twig |
The theme’s settings form. With a config/ folder, the theme has a Settings button. |
config/settings_data.json.example |
The default settings, in presets. |
assets/build/ |
The built stylesheets, script and icon sprite. |
For each page, ClientFence looks for the template in the theme’s html_custom/, then its html/,
then in the templates/client/ folder of each module. A theme cannot inherit another theme’s
templates: copy every file you need.
1. Copy Palisade
Section titled “1. Copy Palisade”Run this in the ClientFence directory, as the site user:
cp -a themes/palisade themes/mybrandChoose the folder name with care:
- Lowercase letters, digits,
-and_only: the settings page address accepts nothing else. - No
adminanywhere in it: a folder withadminin its name is listed as an admin area theme. - Not
palisade,admin_defaultorhuraga: updates write or remove files in those folders.
The web server user must own the folder and be able to write to assets/ and config/. Saving
the theme’s settings fails while assets/ is not writable.
2. Name it
Section titled “2. Name it”Edit themes/mybrand/manifest.json:
{ "name": "My Brand", "version": "1.0.0", "description": "The Example Hosting client area.", "author": "Example Hosting", "author_url": "https://example.com/", "markdown_attributes": { "\\League\\CommonMark\\Extension\\Table\\Table": { "class": "table table-hover" }, "\\League\\CommonMark\\Extension\\CommonMark\\Node\\Inline\\Image": { "class": "img-fluid" } }}markdown_attributes adds CSS classes to what Markdown text becomes, for example a knowledge base
article’s tables and images. The Themes page lists the theme by its folder name; the
theme:list command shows name.
3. Change the templates
Section titled “3. Change the templates”Edit the files in themes/mybrand/html/. Their names tell you what they show:
| Template | Shows |
|---|---|
layout_default.html.twig |
The frame of every signed-in page: menu, top bar, footer. |
layout_public.html.twig |
The full-screen pages: sign-in, sign-up, password reset, maintenance. |
partials/head.html.twig |
The <head>: stylesheets, scripts, meta tags. |
error.html.twig |
The error page. |
mod_<module>_<page>.html.twig |
One page, for example mod_invoice_invoice.html.twig. |
Keep these, or pages that come from the modules break:
- The files
layout_default.html.twig,layout_public.html.twigandpartial_pagination.html.twig: module pages extend or include them. - Palisade’s stylesheet and script (
assets/build/): module pages use its CSS classes and its script’s features. - The
{{ render_widgets('...') }}lines: modules put their content there. {{ svg_sprite() }}, the scriptsclientfence.jsandapi.js, andpartials/i18n.html.twigin the head.
Templates run with strict variables: a missing variable stops the page with an error. Write
settings.my_option|default('1') or test is defined. Twig filters, functions and variables
lists everything a template can use.
4. Add your styles and scripts
Section titled “4. Add your styles and scripts”The simple way: add your own files next to Palisade’s. Put them in themes/mybrand/assets/, for
example assets/css/mybrand.css, and link them in html/partials/head.html.twig, after the line
that loads palisade.css and before the Custom CSS line, so Custom CSS still wins:
{{ 'css/mybrand.css'|asset_url|stylesheet_tag('all') }}{{ 'js/mybrand.js'|asset_url|script_tag }}asset_url points to the active theme’s assets/ folder. Both tags add a version to the address,
so browsers load the new file after each change. script_tag adds the page’s nonce.
To change Palisade’s own stylesheet (Bootstrap and SCSS) or script, rebuild them. A release ships
only the built files; the sources are in src/themes/palisade/ of the
ClientFence repository, at the tag of your version
(for example v1.0.57).
-
On your own computer, copy
assets/src/,build.mjs,package.json,package-lock.jsonandicon-manifest.jsonfrom there into a copy of your theme. -
Make your changes, then build with Node.js 22 or later:
Terminal window npm cinpm run build -
Upload
assets/build/andhtml/partials/asset_version.html.twigtothemes/mybrand/.
Build outside the site: visitors can download most files in a theme folder (not the Twig templates,
config/ or manifest.json), so node_modules/ and sources do not belong there. icon-manifest.json lists the icons in the sprite; a template draws
one with <svg class="icon"><use href="#bell"/></svg>. The build also writes palisade.rtl.css,
the mirrored stylesheet that Arabic, Persian and Hebrew pages load.
5. Follow the script policy
Section titled “5. Follow the script policy”Every page sends a Content Security Policy that only lets trusted scripts run:
- Each
<script>tag needsnonce="{{ csp_nonce }}".script_tagadds it. A script loaded by a trusted script also runs. onclickand otheron...attributes, andjavascript:links, do not run. Attach events withaddEventListenerin a script file.<object>and<embed>are blocked, and<base>may only point to the site itself.- Styles are not restricted:
<style>blocks andstyleattributes work.
Browsers report each blocked script, and System Health shows them under Script policy (see System health).
6. Make the settings page
Section titled “6. Make the settings page”config/settings.html.twig is a form fragment. Each field’s name is a setting: the admin page
fills the field from the saved value, and templates read it as settings.<name>.
<section> <h4 class="card-title mb-3">{{ 'My Brand'|trans }}</h4> <label class="form-check"> <input class="form-check-input" type="checkbox" name="show_banner" value="1"> <span class="form-check-label">{{ 'Show the banner'|trans }}</span> </label> <label class="form-label" for="banner_text">{{ 'Banner text'|trans }}</label> <input class="form-control" type="text" name="banner_text" id="banner_text"></section>{% if settings.show_banner|default('0') == '1' %} <div class="alert alert-info">{{ settings.banner_text|default('') }}</div>{% endif %}- Each
<section>with an<h4>heading gets a button under Jump to Section. - An unticked box is saved as
"0". - A
<select>with the classpageorproductis filled with your pages or products; the classsnippetoffers the sign-in, domain checker and contact forms. - The form runs in a sandbox:
if,for,setand a short list of filters such astransanddefault(see the reference).<script>,<style>andstyleattributes are removed. config/settings_data.json.exampleholds the defaults:{"presets": {"Default": {...}}, "current": "Default"}. Saving writesconfig/settings_data.json, which then wins. Presets saved before you add a field do not have it, so always read settings with|default.- Keep the
custom_css,custom_css_enabledandinject_javascriptfields, thecustom-cssline in the head andpartials/page_end.html.twig, so Custom CSS and Add JavaScript to Client Area Footer keep working. Only super administrators can change them.
A file in assets/ named *.css.html.twig or *.js.html.twig is rendered with the settings each
time you select Apply Changes, and saved without the .html.twig ending. For example,
assets/css/colors.css.html.twig:
:root { --mybrand-accent: {{ settings.accent_color|default('#0e5a7a') }}; }becomes assets/css/colors.css. Link it in the head like any other stylesheet.
7. Activate it
Section titled “7. Activate it”- Go to System → Settings → Theme.
- Under Client Area Themes, select Set as Default on your theme’s row.
- Select Settings on the same row. Your theme starts with the presets in the copied
settings_data.json, so with the Palisade settings you had. Adjust them and select Apply Changes. - Open the client area signed out and as a signed-in client. Check a phone-sized window, dark mode, and a right-to-left language if you offer one.
To go back, select Set as Default on palisade. Each theme keeps its own settings.
To see the installed themes and the active ones from the server:
php console.php theme:list8. Keep it working after updates
Section titled “8. Keep it working after updates”An update never touches themes/mybrand/. That also means Palisade’s fixes and new features do not
reach it. When you copy Palisade, also keep an untouched copy of its templates and settings form,
so you can see what each update changes:
cp -a themes/palisade/html ~/palisade-html-1.0.57cp -a themes/palisade/config ~/palisade-config-1.0.57After each update:
-
Compare the old and the new Palisade, and bring the changes into your theme:
Terminal window diff -ru ~/palisade-html-1.0.57 themes/palisade/htmldiff -u ~/palisade-config-1.0.57/settings.html.twig themes/palisade/config/settings.html.twig -
If you use Palisade’s built files unchanged, copy the new
themes/palisade/assets/build/andhtml/partials/asset_version.html.twiginto your theme. If you rebuild them, rebuild from the new tag. -
Replace your saved copies with the new version, then check the client area again.
An admin area theme
Section titled “An admin area theme”Admin themes work the same way. Copy themes/admin_default to a folder whose name starts with
admin_, for example admin_mybrand, and select Set as Default under Admin Area Themes.
The admin theme has no settings page. If the admin area stops working, rename your folder: the
admin area then falls back to admin_default.

