Admin theme customisation

Bloke · 2025-11-27 03:38:45

Leading question:

Does anybody currently add a file called prefs.json to their admin theme installation folder, to define additional public-side prefs and style blocks?

If I’m reading this Theme code right:

        if (!empty($prefs['textpattern'])) {
            $content = json_encode($prefs['textpattern'], TEXTPATTERN_JSON);
            $out .= \Txp::get('\Textpattern\UI\Script', "textpattern.prefs = jQuery.extend(textpattern.prefs, {$content})").n;
        }

        if (!empty($prefs['style'])) {
            $content = $prefs['style'];
            $out .= \Txp::get('\Textpattern\UI\Style', n.$content.n);
        }

That allows you to add a ‘textpattern’ node to prefs.json in any admin theme folder, which will extend the public JavaScript `textpattern.prefs` object with your own. Presumably that’s for adding JS strings and stuff that your theme might need, over and above what’s in core already.

In addition, it will inject any content defined in a prefs.json ‘style’ node as inline styles.

The above is in addition to using custom.css and/or custom.js, which will read those files (not content) and add them as <link> targets to be loaded with your theme.

I’m only asking because I have a half-baked enhancement that I might squeeze into 4.9.0 if there’s time between now and next weekend, and if nobody is using this prefs.json file, I’m tempted to rename it because it’s a daft name for what it does.

phiw13 · 2025-11-27 06:03:29

I did not know this option eventually existed – and at first sight, it is not documented (I may have missed that though). So no, unused on my side.

jakob · 2025-11-27 07:32:07

Same here.

Bloke · 2025-11-27 07:52:28

That’s what I hoped the answer would be from both people I expect are the only candidates for using this undocumented feature :)

Thank you. If I can get this thing to work then I’ll rename the file to custom.json instead.

Any more people using it?

etc · 2025-11-27 12:19:23

Won’t complain.

Bloke · 2025-11-27 15:04:20

It’s a bit late in the dev cycle for what I have planned today and tomorrow, but this will blow things wide open in preparation for Txp 5, and also make 4.9.0 a truckload more attractive.

First stepping stone is Admin theme prefs

The commit message explains most of it. I think I’ll add a convenience method to the Theme class so you can get theme prefs without having to “construct” them yourself with the internal delimiter. I’ll add that later. But for now, this change means you can bundle prefs and textpacks with your theme to have the strings and settings imported into Txp automatically. Note that you need to actually switch to the theme in question for the stuff to be imported.

I was in two minds about only showing the prefs for the currently seelcted theme. The upside is less clutter. The downside is that when you switch theme, if the incoming theme doesn’t have prefs, you still see the Prefs->Admin Theme subtab until you refresh the page, which is a bit rubbish. That’s simply due to the way the page is built.

We can’t inject the prefs/strings when the theme is instantiated (early in the page flow) because the user authentication takes place afterwards and would open up a security hole; not to mention we wouldn’t be able to set per-user prefs without knowing the user. So we have to introduce them a bit later. But by that time the “old” theme has already been partially loaded and the UI is built with its settings rather than the incoming theme settings. The solution is to double-refresh in the code, but that’s ugly. Ideas welcome.

Strings too, you might find don’t appear on first page load and you need to refresh the admin side or navigate away to show them.

Anyway, more stuff coming soon. Sorry. Just couldn’t help myself.

Bloke · 2025-11-27 15:09:35

P.S. the old prefs.json functionality has been moved to custom.json.

P.P.S. Since there’s no (un)installation of admin themes, you’ll need to manually remove the prefs and strings if you get rid of a theme. There might be a way to hide them if a theme’s not installed, but the change is fairly invasive to the prefs panel and I didn’t want to rock the boat too wildly just before release.

Bloke · 2025-11-28 00:18:09

Drat, it’s not saving the new prefs cos of a permissions issue. Apologies. I’ll debug it in the morning.

Bloke · 2025-11-28 07:43:38

Bloke wrote #341377:

Drat, it’s not saving the new prefs cos of a permissions issue. Apologies. I’ll debug it in the morning.

It is saving again now, with the latest commit.

Weird that I had to split this and put the privs in the initialiser, but the remainder of the code later (for reasons mentioned above). At the time the core saves the prefs, it conveniently “forgot” the privs I’d set in what I thought was an earlier part of the page load, but maybe ‘pre’ really is very very pre-(pagetop). *shrugs*

phiw13 · 2025-11-28 09:23:04

Bloke wrote #341380:

It is saving again now, with the latest commit.

Weird that I had to split this and put the privs in the initialiser, but the remainder of the code later (for reasons mentioned above). At the time the core saves the prefs, it conveniently “forgot” the privs I’d set in what I thought was an earlier part of the page load, but maybe ‘pre’ really is very very pre-(pagetop). shrugs

Thanks for all that. Do you have a small practical example I could use & play with for testing?

Bloke · 2025-11-28 10:33:47

phiw13 wrote #341381:

Do you have a small practical example I could use & play with for testing?

Yep. Add file prefs.json to your theme:

{
    "phw_text_colour": {
        "val": "#333",
        "html": "text_input",
        "position": "10"
    },
    "phw_background_colour": {
        "val": "#2596be",
        "html": "text_input",
        "position": "20"
    }
}

Add file textpack.txp:

#@prefs
#@language en, en-gb, en-us
phw_background_colour => Background colour
phw_text_colour => Text colour

Those prefs will show up on the Preferences panel (Managing Editor and Publisher roles only). Then you can use those prefs in your theme to let people mess with colours:

$bg_colour = get_pref($this->name.PREF_THEME_DELIMITER.'phw_background_colour');

(not the most amazing playground, since these values will likely be in the CSS file so you’d need to parse them to inject the values, but you hopefully get the idea. You could use it for positional stuff, grid columns, layout tweaks that you want to expose to users. Or even maybe a select list of sub-variants of the theme for common scenarios like a more image-oriented workflow, or article-centric one).

I’ll add a convenience method at some point to make it a bit nicer than building your own ‘path to my pref value’. When I’m sure this is actually going to work how I intend.

Bloke · 2025-11-28 10:41:39

Addendum: you probably don’t need to use the phw_ prefix for your prefs, because they are all automatically prefixed with your theme name and a pipe symbol. That’s good enough to avoid clashes with other themes.

phiw13 · 2025-11-28 12:09:52

Thank you, Stef. That gives a starting idea on the possibilities.

I’ll try to play a little with this over the WE.

etc · 2025-11-28 12:11:36

You did it! Looks promising, and makes me question the admin theme role. Our existing themes mostly define css rules and a bit of js to output the hard-coded markup, though they have full php powers. Do they need more flexibility, to be able to define their own presentation? Should core just send them json (say) data and provide some api for read/write requests?

Bloke · 2025-11-28 13:26:26

etc wrote #341388:

You did it! Looks promising, and makes me question the admin theme role.

Precisely. I have actually got (somewhere…) an Admin->Panel class, half finished, which generalises the process of building a back-end screen. That should mesh nicely with this stuff.

If we can get to the point where core has a library of tools, widgets and page building layers that anyone can tap into, the admin theme is basically a collection of these things and some CSS wrapped around data.

We’re definitely on the right track with the UI library, and the Table classes and stuff like that. Theme Prefs adds another string to it, and I’m planning to demo how useful their involvement is in a day or two.

Also, of the panels I’ve converted so far, extending the tables via plugin works (even though it’s not ideal as the core columns always come first). That probably needs rethinking a bit so I might pause where we are and perhaps, as you say, we can retool the way it works as we iterate Txp 5.

Textpattern CMS

Textpattern CMS support forum

#1 2025-11-27 03:38:45