Custom CSS for Proclaim: where should it live?

[bcordis]

Split out of #1653. While auditing per-section permissions we found cssedit declared in admin/access.xml since the original 2013 ACL pass, guarding a CSS editor that was never built. Rather than keep a permission for a phantom feature, the section was dropped — but the underlying gap is real and worth designing properly.

Where custom CSS stands today

There is no supported mechanism. The options a site owner actually has:

1. Template Codes — the CodeMirror editor writes real template .php files into the view folders. Its own help text says "Put the php and HTML code here… Put in your own CSS tags too." So custom CSS ends up inline in a PHP override.
2. Joomla template overrides in the site template.
3. Editing Proclaim's shipped CSS in media/css/, which an update overwrites.

None is good. (1) mixes presentation into a code override and needs someone comfortable with PHP; (3) actively loses work on update. The realistic outcome is people hacking files that get overwritten.

The proposal on the table

@bcordis's initial read is that this belongs in template settings rather than as a separate editor screen, which has a lot going for it — Proclaim templates already carry the presentation params (pagination_style, listing_item_style, embedshare), so styling decisions are already made there, and per-template CSS follows the multi-campus model where different campuses run different templates.

Sketch, to argue with:

• a CSS textarea on the template edit form, CodeMirror-backed like Template Codes
• written to a file the Web Asset Manager loads after Proclaim's own styles, so it wins on specificity without !important
• per template, so a campus can restyle without touching the others
• governed by the existing template section, so no new ACL section is needed

Open questions

1. Per template, or one global sheet, or both? Per template matches multi-campus. A global sheet is simpler and covers "make all of Proclaim match my site". Both means deciding load order.
2. Stored in params or as a file? A param is backed up and restored with the component and needs no writable directory. A file is cacheable and serves without a DB hit. If it is a file, what happens when the directory is not writable?
3. What is the update story? Whatever we choose has to survive an update untouched — that is the main thing the current situation fails at.
4. Is a CSS editor a security surface? CSS can load remote resources and, with url() and injected content, is not entirely inert. It would be authorable only by someone who can already edit templates, but worth stating.
5. Does this replace or complement Template Codes? If someone can write CSS in template settings, the "put your CSS tags in the override" advice should stop being the documented answer.
6. Scope against the Layout Editor. Some of what people reach for CSS to fix may be better solved by layout settings. Worth knowing which problems we are actually trying to solve before choosing a mechanism.

What would resolve this

A decision on 1 and 2, which determines everything else. Once there is a shape, it becomes an issue with an implementation plan — and if it ships as its own manageable thing rather than a template field, cssedit earns its ACL section back, honestly this time.

[bcordis]

Went looking for evidence on the six questions. Most of them turn out to be answerable from what Proclaim already has, so here is a concrete proposal rather than more options.

Q1 — per template, and here is why that is not a close call

#__bsms_templates already carries both of these:

`params`      LONGTEXT,
`location_id` INT(3) DEFAULT NULL,
KEY `idx_template_location` (`location_id`)

So a CSS param on a template is per-campus CSS, with no new plumbing and no new concept for an administrator to learn — it follows the multi-campus model that already exists. @bcordis's instinct that this belongs in template settings holds up on inspection.

I would still add a component-level sheet in #__bsms_admin.params for "make all of Proclaim match my site", loaded before the template's so the template wins. That is a one-line ordering decision, not a second mechanism.

Q2 — params, not a file. Three independent reasons

Backup. Cwmbackup dumps the #__bsms_* tables. CSS in params is backed up and restored with everything else; a file under media/com_proclaim/ is not. Someone who restores a backup and finds their styling gone will reasonably call that data loss.

The media directory is component-owned. proclaim.xml installs media → com_proclaim, and proclaim.script.php maintains an explicit delete list of stale files under it:

'/media/com_proclaim/css/icons.css',
'/media/com_proclaim/css/bsmImport.css',
'/media/com_proclaim/css/general.min.min.css',
...

Putting user-authored content into a directory the installer actively prunes invites exactly the update-time loss we are trying to fix.

The asset manifest is generated. media/joomla.asset.json is built from build/media_source/ and is gitignored — so a user CSS file cannot be declared in it; the build would overwrite the declaration. Runtime registration is required either way, and addInlineStyle() is already used in ColorPickerField.php:469, so there is precedent in the codebase.

Q3 — the update story, which is the whole point

Params live in #__bsms_templates / #__bsms_admin. An update touches neither. That is the single thing today's "put your CSS in a Template Code override" answer fails at, because an override is a file.

Q4 — security: a content surface, not a new privilege

Authoring would require core.edit on com_proclaim.template — which as of #1653 is genuinely enforced rather than falling back to the component. So this grants nothing to anyone who could not already edit templates and put arbitrary CSS (and PHP) in them.

Two things still worth doing, because CSS is not inert:

• store raw, escape on output so a </style> in the value cannot break out
• be explicit that url() can fetch remote resources; that is inherent to CSS and matches what a template override can already do, but it should be a stated property rather than a surprise

Q5 — complements Template Codes

Template Codes stays for structural overrides. What should change is the documentation: JBS_TPLCODE_CODE_DESC currently says "Put in your own CSS tags too", and that advice should stop being the answer once there is a proper place.

Q6 — the one I cannot answer from the code

Which problems people actually reach for CSS to solve. Some are probably Layout Editor settings that already exist or should. Without that, we risk building a general escape hatch for a set of specific gaps.

This is the question I would most like input on — a handful of real "I had to write CSS because…" examples would shape the default styling more usefully than any amount of design here.

Proposed shape

• custom_css param on the template edit form, CodeMirror-backed like Template Codes
• optional component-level custom_css in Proclaim options
• emitted via addInlineStyle() — component sheet first, then the active template's
• governed by the existing template section; no new ACL section, so cssedit stays dropped

The one genuine tradeoff left

Inline <style> is not browser-cacheable and is re-sent on every page. Fine for a few dozen rules; wasteful for a large sheet.

The alternative — write the params to a generated file on save and load that — buys caching but reintroduces the writable-directory problem and needs a fallback when the directory is not writable.

My suggestion is to start inline, and revisit if anyone produces a sheet large enough to matter. Being wrong about that is cheap and reversible; being wrong about params-vs-file is not.

What I would want agreed before implementing

1. component-level sheet as well as per-template, or template-only?
2. inline to start, or straight to a generated file?
3. any cap on size?

1 and 2 are the ones that change the code.

[bcordis]

Built it — #1725. Both levels, inline to start, as agreed.

level	stored in	edited at
site-wide	#__bsms_admin.params	Administration → Custom CSS tab
per template	#__bsms_templates.params	template form, Template Overrides

Component sheet loads first so a template refines it rather than replacing it. Emitted once per request from the site Dispatcher, so it reaches everything Proclaim renders without touching the twelve site views.

Two things worth reporting back here rather than leaving in the PR.

The site-wide sheet went to #__bsms_admin.params, not Joomla Options. Proclaim has two "component settings" stores — its own Administration screen writes #__bsms_admin.params, while Options writes #__extensions.params. Only the first is a #__bsms_* table, so only the first is covered by Cwmbackup. Putting it in Options would have quietly broken the backup argument that decided params-vs-file in the first place.

The </style> escape needed to be broader than it first looks. A browser's tokeniser ends the element on any of these:

</style   </STYLE   </StYlE   < /style   </ style   <\t/style   </\nstyle

All seven are in a data provider, and neutering the sanitiser fails all seven. Verified live on j6-dev with a sheet containing </style><script>alert(1)</script> — zero script elements produced.

url() is deliberately left alone, with a test saying so, so nobody "hardens" it later: fetching a remote resource is inherent to CSS, stripping it breaks web fonts and background images, and it removes no capability from someone who can already put arbitrary PHP in a template override.

---

Q6 is still the open one, and it is the one that would change what we build next. Which problems do people actually reach for CSS to solve? Some are probably Layout Editor settings that already exist, or should. A handful of real "I had to write CSS because…" examples would tell us whether this escape hatch is the fix or a symptom.

The other thing to revisit eventually is inline-vs-file. Inline is not browser-cacheable and re-sends on every page — fine for a few dozen rules, wasteful for a large one. Worth changing only if someone produces a sheet big enough to matter, which is exactly the kind of thing those examples would surface.

[bcordis]

Closing this out. The two questions it existed to settle — Q1 per-template vs global, and Q2 params vs file — were both decided and are both shipped, which is what this said would resolve it.

What shipped

Three levels, not the two reported above. The per-section level landed later in #1817 and was never written up here:

level	stored in	edited at	shipped in
site-wide	#__bsms_admin.params.custom_css	Administration → Custom CSS tab	#1725
per template	#__bsms_templates.params.custom_css	template form → Template Overrides	#1725
per landing section	#__bsms_templates.params.<id>_custom_css	Layout Editor → section gear	#1817

Site-wide and template sheets are emitted once per request from site/src/Dispatcher/Dispatcher.php:74; section sheets from Cwmlandingpage/HtmlView.php:132. All in 10.5.8.

The section level is worth a note because it solves something the original design did not address: the two page-wide sheets could not style one section of a landing page without hand-writing a selector against markup that might change. Each section's CSS is now wrapped in [data-section="<id>"] { … } using native CSS nesting, so rules cannot leak sideways and an author writes as though the section were the document root. Browsers without nesting drop the block entirely — absent rather than misapplied, which is the safe direction to fail. Section ids are validated against /^[a-z0-9_-]+$/ before reaching the attribute selector, since landing_layout is hand-editable JSON.

Against the original questions

• Q1, Q2, Q3 — settled as proposed. Params, both levels, untouched by an update, covered by Cwmbackup.
• Q4 — sanitise() neutralises anything a browser's tokeniser accepts as ending the element; all seven variants are in a data provider. url() is deliberately left alone, with a test asserting so, so nobody hardens it later and breaks web fonts.
• Q5 — not done. JBS_TPLCODE_CODE_DESC still reads "Put in your own CSS tags too", which is the advice this discussion said should stop being the answer. Tracked as Template Code help text still tells people to put CSS in a PHP override #1919. The wiki half is done: the Template Customization Guide now documents all three levels, load order, the nesting caveat and what the sanitiser does (Proclaim.wiki e3c6400) — until today the feature had no user documentation at all.
• Q6 — still unanswered, and closing this does not answer it. Which problems people actually reach for CSS to solve had no replies here in eight days, which is the expected outcome: the question needs users, and a design discussion is not where they are. If it gets asked properly it belongs in release notes or somewhere users read, not here.

The one open tradeoff

Inline <style> is not browser-cacheable and re-sends on every page. That was a deliberate, reversible choice — revisit only if someone produces a sheet large enough to matter. Recorded in the wiki as guidance rather than left as folklore, and it is trigger-based rather than scheduled work, so it does not need an open discussion to hold it.

One thing that came out of this later

In #843, custom CSS turns out to be what makes params-only template presets viable: a preset can carry custom_css and all seven section sheets as ordinary params, so a shipped starter template can look genuinely different without distributing a single file or #__bsms_styles row. That was not a goal here, but it is a second payoff from the params-not-a-file decision.