Skip to content

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.

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.

Run this in the ClientFence directory, as the site user:

Terminal window
cp -a themes/palisade themes/mybrand

Choose the folder name with care:

  • Lowercase letters, digits, - and _ only: the settings page address accepts nothing else.
  • No admin anywhere in it: a folder with admin in its name is listed as an admin area theme.
  • Not palisade, admin_default or huraga: 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.

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.

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.twig and partial_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 scripts clientfence.js and api.js, and partials/i18n.html.twig in 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.

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).

  1. On your own computer, copy assets/src/, build.mjs, package.json, package-lock.json and icon-manifest.json from there into a copy of your theme.

  2. Make your changes, then build with Node.js 22 or later:

    Terminal window
    npm ci
    npm run build
  3. Upload assets/build/ and html/partials/asset_version.html.twig to themes/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.

Every page sends a Content Security Policy that only lets trusted scripts run:

  • Each <script> tag needs nonce="{{ csp_nonce }}". script_tag adds it. A script loaded by a trusted script also runs.
  • onclick and other on... attributes, and javascript: links, do not run. Attach events with addEventListener in a script file.
  • <object> and <embed> are blocked, and <base> may only point to the site itself.
  • Styles are not restricted: <style> blocks and style attributes work.

Browsers report each blocked script, and System Health shows them under Script policy (see System health).

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 class page or product is filled with your pages or products; the class snippet offers the sign-in, domain checker and contact forms.
  • The form runs in a sandbox: if, for, set and a short list of filters such as trans and default (see the reference). <script>, <style> and style attributes are removed.
  • config/settings_data.json.example holds the defaults: {"presets": {"Default": {...}}, "current": "Default"}. Saving writes config/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_enabled and inject_javascript fields, the custom-css line in the head and partials/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.

  1. Go to System → Settings → Theme.
  2. Under Client Area Themes, select Set as Default on your theme’s row.
  3. 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.
  4. 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:

Terminal window
php console.php theme:list

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:

Terminal window
cp -a themes/palisade/html ~/palisade-html-1.0.57
cp -a themes/palisade/config ~/palisade-config-1.0.57

After each update:

  1. 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/html
    diff -u ~/palisade-config-1.0.57/settings.html.twig themes/palisade/config/settings.html.twig
  2. If you use Palisade’s built files unchanged, copy the new themes/palisade/assets/build/ and html/partials/asset_version.html.twig into your theme. If you rebuild them, rebuild from the new tag.

  3. Replace your saved copies with the new version, then check the client area again.

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.